75 lines
4.9 KiB
Markdown
75 lines
4.9 KiB
Markdown
# CRUX Documentation
|
|
|
|
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 | `backend/` | Core module docs and backend-specific guides |
|
|
| Admin frontend | `apps/admin/` | [Admin app docs](./apps/admin/Readme.md) |
|
|
| Shared packages | `packages/` | [Packages index](./packages/Readme.md) |
|
|
| Devtools | `apps/admin/src/devtools/` | [Devtools docs](./devtools/Readme.md) |
|
|
| Core modules | `backend/app/base_modules/`, `apps/admin/src/core/` | [Core modules](#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](./apps-architecture/react-frontend/Readme.md) |
|
|
| Backend | AdonisJS backend apps and backend modules | [Backend architecture](./apps-architecture/backend/Readme.md) |
|
|
|
|
## 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](./core-modules/access-control/Readme.md) |
|
|
| Account Settings | Admin profile endpoints | `apps/admin/src/core/AccountSettings/` | [Overview](./core-modules/account-settings/Readme.md) |
|
|
| Auth | `backend/app/base_modules/Auth/` | `apps/admin/src/core/Auth/` | [Overview](./core-modules/auth/Readme.md) |
|
|
| Fallback Screens | Frontend-only | `apps/admin/src/core/FallbackScreens/` | [Overview](./core-modules/fallback-screens/Readme.md) |
|
|
| File Manager | `backend/app/base_modules/FileManager/` | `apps/admin/src/core/FileManager/` | [Overview](./core-modules/file-manager/Readme.md) |
|
|
| Permission | Permission service and policies | `apps/admin/src/core/Permission/` | [Overview](./core-modules/permission/Readme.md) |
|
|
|
|
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:
|
|
|
|
1. What user or system problem does the module solve?
|
|
2. Where is the backend code?
|
|
3. Where is the frontend code?
|
|
4. What are the main flows from route to service to UI?
|
|
5. What data contracts cross app boundaries?
|
|
6. Which files should a developer edit for common changes?
|
|
7. What extension points are supported?
|
|
8. 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`.
|