Reorganize app workspaces and align Admin architecture

2026-07-17 13:46:21 +00:00
parent ba691d3a0c
commit 0ba01cd111
183 changed files with 3745 additions and 4354 deletions
@@ -0,0 +1,61 @@
+# 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.