# Using the framework

Server apps using this framework follow an **MVC-style** split with this naming: **M**odel, **V** = controller layer, **C** = service layer (business logic).

# Configuration

The [`config/`](../config) directory contains predefined configuration for an AdonisJS app that uses this framework. Settings there are **overridden** by any file of the same name in the **host** application’s `config/` directory (standard Adonis merge/override behavior).

## Peer dependencies and macros

Several libraries are declared as [**peer dependencies**](../package.json) instead of being shipped inside the published package. The host app installs them; Akago and the app therefore share the **same** resolved instances of those modules.

Akago extends those libraries at runtime with **macros** (e.g. Japa `Assert` / `Group`, Adonis `Route`, Vine, Lucid `Database`). Macros attach to whatever instance Node loads from `node_modules`—they are not a fork or a pre-bundled patch of the upstream package.

**Takeaway:** install and keep the peer dependencies (within the ranges in `package.json`) in the host project if you rely on those features. If a peer is missing or a very different version is installed, macro-based APIs may be absent at runtime or typings may not line up.

# Modules

## CRUD

### Extra data

To return additional database data in model serialization:

- Load it in the query (see [Lucid](https://lucid.adonisjs.com/docs/), e.g. [`withCount`](https://lucid.adonisjs.com/docs/model-query-builder#withcount)).
- Expose it with a getter on the model.

## Auth

Auth is driven by **AuthContext**.

In the HTTP server pipeline, `AuthContext` is filled by **AuthMiddleware**.

## API exceptions

API errors are represented by [`AKAPIException`](../modules/exceptions/api_exception.ts). It subclasses Adonis’s generic [`E_HTTP_EXCEPTION`](https://docs.adonisjs.com/guides/exception-handling): the framework still owns the exception pipeline, but the JSON body is API-oriented—a stable `errorId` (the exception `code`), a `message`, and optionally a `cause` (omitted in production unless explicitly allowed).

The library provides many **ready-made** `AKAPIException` instances (auth, validation, not found, conflicts, etc.) as static properties on `AKAPIException`.

In **your** app, signal domain failures by **throwing** `AKAPIException` (reuse the built-ins or `new AKAPIException(status, code, message, …)` for your own codes) so clients always see the same contract.

Responses are produced by the exception handler [`AKHttpExceptionHandler`](../modules/exceptions/http_exception_handler.ts). It also maps several non-API errors (Vine validation, route not found, selected PostgreSQL error codes, etc.) to `AKAPIException`. Register this class in your Adonis exception handling setup like any other `ExceptionHandler` subclass.

## Tests

[`tests/`](../tests) holds **helpers** for writing tests, not the test suite itself. Feature and unit tests live next to code in `*.test.ts` files.

## Emails

Emails use [Edge](https://edgejs.dev) and [MJML](https://mjml.io/). MJML has limits; some were intentionally relaxed to match product design.

On a running server, previews are available under `/event` (example: [https://api.libelaw.fr/event](https://api.libelaw.fr/event)).

Most templates build on `default_html.edge`, with optional blocks driven by `emailPayload()` on an `AKEvent` (e.g. `ResourceMessageNewEvent` enables the message and missionSmall components).

## Caveats

- **Model serialization:** Never return raw model instances from controllers—call `serialize()` first. Otherwise getters that depend on `AuthContext` (e.g. `Mission.viewerStatus()`) may run after the context is already closed.
- **TypeScript:** Some generics-heavy patterns in Akago trade IDE ergonomics for flexibility (e.g. static overrides on generic bases).

## Recommended additional packages

- [@akago/adonisjs-drhttp](https://www.npmjs.com/package/@akago/adonisjs-drhttp)
- [@akago/adonisjs-log-http](https://www.npmjs.com/package/@akago/adonisjs-log-http)
