# 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

```txt
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:

```txt
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.