Backend Architecture

This guide is a short backend architecture reference for CRUX backend apps.

The current backend is based on AdonisJS v6. Use the official AdonisJS folder structure as the default baseline:

https://v6-docs.adonisjs.com/guides/getting-started/folder-structure

Main Idea

Keep the backend close to the standard AdonisJS structure. Add project-specific folders only when they make ownership clearer.

Default Folders

Folder	Purpose
`app/`	Application code: controllers, services, middleware, policies, validators, and domain logic.
`start/`	Boot lifecycle files such as routes, kernel setup, env loading, and event registration.
`config/`	Runtime configuration for AdonisJS and installed packages.
`database/`	Migrations and seeders.
`bin/`	Entrypoints for server, console, and tests.
`public/`	Static files and generated public assets.
`tests/`	Backend tests.

Basic Flow

start/routes.ts
  -> controller
  -> validator / policy
  -> service
  -> model / database / external service

Controllers should handle HTTP concerns. Services should hold business logic. Validators should own request validation. Policies and abilities should own authorization.

Module Folders

If a backend app has reusable or generated modules, keep each module's files together when that improves maintainability.

Example:

app/base_modules/ModuleName/
  controller/
  services/
  validator/
  policy/
  routes.ts

This is an app convention, not an AdonisJS requirement. Prefer the default AdonisJS structure unless a module boundary is useful.

Rules

Follow AdonisJS conventions first.
Keep HTTP logic out of services.
Keep business logic out of controllers.
Validate request input before calling services.
Use policies or abilities for protected operations.
Document module-specific architecture in module docs, not in this general guide.

2.4 KiB Raw Blame History