Jubiloop Controller & Routing Guide

Overview

This guide provides quick getting started examples on how to create and implement controllers, routes, validators, and transformers in the Jubiloop backend application. For more detailed information, please refer to the AdonisJS documentation.

Table of Contents

• Controllers
• Validators
• Transformers
• Routes
• Authentication
• Authorization
• Response Structure

Creating Controllers and Routes

When implementing new routes in Jubiloop, follow these general steps:

1. Create validator(s) to validate incoming data
2. Create transformer(s) to format outgoing data
3. Create controller(s) with handlers for the specific operations
4. Add routes to expose the controller endpoints
5. Apply authentication middleware as needed

This guide provides examples based on the existing codebase. For comprehensive documentation, refer to the AdonisJS Controller Guide and AdonisJS Routing Guide.

Controllers

Controllers are the central components that handle HTTP requests, process business logic, and return standardized responses. They act as the bridge between routes and your application's models/services.

Controller Structure

Controllers in Jubiloop follow a class-based approach with well-defined methods for specific operations:

import SomeTransformer from '#transformers/some_transformer'
import { someValidator } from '#validators/some_validator'
import type { HttpContext } from '@adonisjs/core/http'

import { renderSuccessResponsePayload } from '../lib/utils/response.js'

export default class SomeController {
  async someMethod({ request, response }: HttpContext) {
    const payload = await request.validateUsing(someValidator)
    const result = await SomeModel.create(payload)

    return response.created(
      renderSuccessResponsePayload({
        data: new SomeTransformer(result).toObject(),
        message: 'Operation completed successfully!',
      }),
    )
  }
}

Example: Sessions Controller

import User from '#models/user'
import UserTransformer from '#transformers/user_transformer'
import { signInValidator } from '#validators/session'
import { HttpContext } from '@adonisjs/core/http'

import { renderSuccessResponsePayload } from '../lib/utils/response.js'

export default class SessionsController {
  async signIn({ request, response, auth }: HttpContext) {
    const { email, password, rememberMe } = await request.validateUsing(signInValidator)
    const user = await User.verifyCredentials(email, password)
    await auth.use('web').login(user, !!rememberMe)

    response.created(
      renderSuccessResponsePayload({
        data: new UserTransformer(user).toObject(),
        message: 'Logged in successfully',
      }),
    )
  }
}

Validators

Validators ensure that incoming data meets specific criteria before processing.

Validator Structure

Validators in Jubiloop use VineJS for validation:

import vine from '@vinejs/vine'

export const someValidator = vine.compile(
  vine.object({
    field1: vine.string().trim().minLength(1),
    field2: vine.number().min(1),
    optionalField: vine.boolean().optional(),
  }),
)

Custom Error Messages

import vine, { SimpleMessagesProvider } from '@vinejs/vine'

export const someValidator = vine.compile(
  vine.object({
    // validation rules
  }),
)

someValidator.messagesProvider = new SimpleMessagesProvider({
  'field1.minLength': 'Field1 must be at least 1 character long',
})

Example: Registration Validator

import vine, { SimpleMessagesProvider } from '@vinejs/vine'

export const signUpValidator = vine.compile(
  vine.object({
    name: vine.string().trim().minLength(1),
    email: vine
      .string()
      .normalizeEmail({
        all_lowercase: true,
      })
      .unique({
        table: 'users',
        column: 'email',
      }),
    password: vine
      .string()
      .trim()
      .minLength(8)
      .regex(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]+$/)
      .confirmed({
        confirmationField: 'passwordConfirmation',
      }),
  }),
)

signUpValidator.messagesProvider = new SimpleMessagesProvider({
  'password.regex':
    'Password must be at least 8 characters long, include one lowercase letter, one uppercase letter, one digit, and one special character (@$!%*?&).',
})

Transformers

Transformers format model data for API responses using AdonisJS v7's BaseTransformer. They live in app/transformers/ and use this.pick() for field selection. Types are auto-generated in .adonisjs/client/data.d.ts.

Transformer Structure

import SomeModel from '#models/some_model'
import { BaseTransformer } from '@adonisjs/core/transformers'

export default class SomeTransformer extends BaseTransformer<SomeModel> {
  toObject() {
    return this.pick(this.resource, ['id', 'name', 'createdAt'])
  }

  forDetailed() {
    return {
      ...this.toObject(),
      updatedAt: this.resource.updatedAt.toJSDate().toISOString(),
    }
  }
}

Example: User Transformer

import User from '#models/user'
import { BaseTransformer } from '@adonisjs/core/transformers'

export default class UserTransformer extends BaseTransformer<User> {
  toObject() {
    return this.pick(this.resource, ['id', 'email', 'name'])
  }
}

Usage in Controllers

// Default representation
data: new SomeTransformer(model).toObject()

// Named variant
data: new SomeTransformer(model).forDetailed()

Routes

Routes define the HTTP endpoints that clients can access in your application. They are defined in start/routes.ts and organized into public (unauthenticated) and authenticated groups.

Adding Public Routes

Public routes don't require authentication:

// In start/routes.ts
function getPublicRoutes() {
  return router.group(() => {
    // Existing routes
    router.post('/sign-in', [SessionsController, 'signIn'])

    // Add your new public routes here
    router.get('/some-public-data', [YourController, 'publicMethod'])
  })
}

Adding Protected Routes

Protected routes require user authentication:

// In start/routes.ts
function getAuthenticatedRoutes() {
  return router
    .group(() => {
      // Existing routes
      router.get('/validate-session', [SessionsController, 'validateSession'])

      // Add your new protected routes here
      router.get('/some-protected-data', [YourController, 'protectedMethod'])
      router.post('/some-resource', [YourController, 'createResource'])
    })
    .use(middleware.auth())
}

Route Structure

router
  .group(() => {
    router.get('/health', async ({ response }) => {
      response.ok({})
    })
    getAuthenticatedRoutes()
    getPublicRoutes()
  })
  .prefix('api')

For more details on AdonisJS routing, see the official documentation.

Authentication

Jubiloop uses Better Auth integrated with AdonisJS. Refer to the Authentication Documentation for details.

Authorization

Jubiloop uses AdonisJS Bouncer to control access to controller actions.

Authorization with Bouncer

Bouncer provides a way to define permission rules for your controllers:

• Abilities: Functions suitable for simple authorization checks across controllers
• Policies: Classes for controller-specific authorization logic, typically one per resource

To use Bouncer in your controllers:

// Using abilities
async someMethod({ bouncer, response }: HttpContext) {
  if (await bouncer.allows('editResource', resource)) {
    // User is authorized to edit
  } else {
    return response.forbidden()
  }
}

// Using policies
async someMethod({ bouncer, response }: HttpContext) {
  if (await bouncer.with(ResourcePolicy).denies('update', resource)) {
    return response.forbidden()
  }

  // Continue with authorized action
}

For more details, see the AdonisJS Authorization Documentation.

Response Structure

All controller responses in Jubiloop follow a standardized format to ensure consistency across the API:

export type TResponsePayload<TData, TMeta = any> = {
  data?: TData // Main response data
  messages?: TResponseMessage[] // Success/info messages
  errors?: TResponseError[] // Error messages
} & TMeta // Additional metadata

export type TResponseMessage = {
  title: string // Main message text
  description?: string // Optional details
}

export type TResponseError = {
  message: string // Error message text
}

Helper Functions

Controllers should use these utility functions to generate consistent responses:

// Success response with data and a message
renderSuccessResponsePayload({
  data: someData,
  message: 'Operation successful',
})

// Error response
renderErrorResponsePayload({
  errorMessage: 'Something went wrong',
})

Controller Response Examples

Success response from a controller:

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Example Item"
  },
  "messages": [
    {
      "title": "Item created successfully"
    }
  ]
}

Error response from a controller:

{
  "errors": [
    {
      "message": "Validation failed"
    }
  ]
}

Complete Controller Example

Here's a complete example of a controller with standard patterns:

import Item from '#models/item'
import ItemTransformer from '#transformers/item_transformer'
import { itemValidator } from '#validators/item'
import { HttpContext } from '@adonisjs/core/http'

import { renderErrorResponsePayload, renderSuccessResponsePayload } from '../lib/utils/response.js'

export default class ItemsController {
  async index({ response }: HttpContext) {
    const items = await Item.all()

    return response.ok(
      renderSuccessResponsePayload({
        data: items.map((item) => new ItemTransformer(item).toObject()),
        message: 'Items retrieved successfully',
      }),
    )
  }

  async store({ request, response }: HttpContext) {
    const payload = await request.validateUsing(itemValidator)
    const item = await Item.create(payload)

    return response.created(
      renderSuccessResponsePayload({
        data: new ItemTransformer(item).toObject(),
        message: 'Item created successfully',
      }),
    )
  }

  async show({ params, response }: HttpContext) {
    const item = await Item.find(params.id)

    if (!item) {
      return response.notFound(renderErrorResponsePayload({ errorMessage: 'Item not found' }))
    }

    return response.ok(
      renderSuccessResponsePayload({
        data: new ItemTransformer(item).toObject(),
        message: 'Item retrieved successfully',
      }),
    )
  }
}