# CRUX Architecture

System-level docs and stack-scoped convention guides. Built-in feature docs live in `docs/core/`, project-module docs in `docs/modules/`, single-app docs with the app (`apps/<app>/Readme.md`).

## Stack Guides

| Guide                                                     | Applies to                                        |
| --------------------------------------------------------- | ------------------------------------------------- |
| [React frontend architecture](./react-frontend/Readme.md) | Frontend apps and frontend modules under `apps/*` |
| [Backend architecture](./backend/Readme.md)               | AdonisJS backend apps and backend modules         |
| [Next.js web architecture](./web/Readme.md)               | The public website (`apps/web/`)                  |

## System Overview

| App            | Source          | Stack        | Role                                                 |
| -------------- | --------------- | ------------ | ---------------------------------------------------- |
| Backend API    | `apps/backend/` | AdonisJS v6  | REST API, business logic, database, authorization    |
| Admin frontend | `apps/admin/`   | React (Vite) | Admin panel: core modules, devtools, project modules |
| Public website | `apps/web/`     | Next.js      | Server-rendered public site fed by the public API    |

```txt
┌──────────────────┐   authenticated REST    ┌──────────────────────┐
│  Admin (React)   │────────────────────────►│  Backend (AdonisJS)  │
│  apps/admin      │◄────────────────────────│  apps/backend        │
└──────────────────┘          DTOs           └──────────┬───────────┘
                                                        │
                                     public REST +      │  cache purge
                                     revalidation hooks │  webhooks
                                                        ▼
                                          ┌──────────────────────────┐
                                          │  Public site (Next.js)   │
                                          │  apps/web                │
                                          └──────────────────────────┘
```

Apps share contracts, never runtime code:

- **Admin ↔ Backend** — authenticated REST, authorized per action via policies and permission slugs. See [Auth](../core/auth/Readme.md), [Access Control](../core/access-control/Readme.md), [Permission](../core/permission/Readme.md).
- **Web ↔ Backend** — public REST plus cache revalidation webhooks. See [Web Manager integration](../core/web-manager/integration.md).

Feature-scoped contracts (DTOs, cache tags, env vars) live next to the feature in `docs/core/<feature>/integration.md`.

## Shared Packages

`packages/` holds `@crux-kit/*` packages shared across apps. Each documents itself in its own `Readme.md`; see the [Packages index](../packages/Readme.md).