This is documentation home for the CRUX monorepo. Use it for system-level architecture, application guides, shared package references, and core module documentation.

Monorepo Map

Area	Source	Documentation
Backend API	`apps/backend/`	Core module docs and backend-specific guides
Admin frontend	`apps/admin/`	Admin app docs
Shared packages	`packages/`	Packages index
Devtools	`apps/admin/src/devtools/`	Devtools docs
Core modules	`apps/backend/app/base_modules/`, `apps/admin/src/core/`	Core modules
Future apps	`apps/*`	Add an app page under `docs/apps/`

App Architecture

Architecture	Scope	Documentation
React frontend	Frontend apps and frontend modules under `apps/*`	React frontend architecture
Backend	AdonisJS backend apps and backend modules	Backend architecture

Core Modules

Core modules are reusable admin panel areas that may have both backend and frontend implementations.

Module	Backend	Frontend	Documentation
Access Control	Admin, Role, Permission base modules	`apps/admin/src/core/AccessControl/`	Overview
Account Settings	Admin profile endpoints	`apps/admin/src/core/AccountSettings/`	Overview
Auth	`apps/backend/app/base_modules/Auth/`	`apps/admin/src/core/Auth/`	Overview
Fallback Screens	Frontend-only	`apps/admin/src/core/FallbackScreens/`	Overview
File Manager	`apps/backend/app/base_modules/FileManager/`	`apps/admin/src/core/FileManager/`	Overview
Permission	Permission service and policies	`apps/admin/src/core/Permission/`	Overview

Add a new page when the information has a stable owner. Keep temporary notes in issue trackers or task files until they are worth maintaining.

How To Write Module Docs

Each module should answer these questions:

What user or system problem does the module solve?
Where is the backend code?
Where is the frontend code?
What are the main flows from route to service to UI?
What data contracts cross app boundaries?
Which files should a developer edit for common changes?
What extension points are supported?
What behavior should not be changed without a migration plan?

Prefer short sections, source paths, and concrete examples over long prose.

Documentation Rules

Use Readme.md as the index for each folder.
Use relative links between documentation pages.
Reference source files with repository-relative paths.
Keep backend and frontend details separate when their ownership differs.
Document current behavior first, then list planned work under a Planned Work section.
Update docs in the same change when modifying routes, DTOs, permissions, storage contracts, package APIs, or module state ownership.

Local Development

Common root scripts:

Command	Purpose
`npm run dev:backend`	Start the AdonisJS backend.
`npm run dev:admin-app`	Start the React admin app.
`npm run dev:all`	Start backend and admin app together.
`npm run build:backend`	Build the backend.
`npm run build:admin`	Build the admin app.

For product overview, setup details, and environment variables, see the project root Readme.md.