amaliadwiy
a0ca6be8e1
Move architecture, testing, and dev tools detail into docs/ and reference them via @path pointers to keep CLAUDE.md slim. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
67 lines
3.2 KiB
Markdown
67 lines
3.2 KiB
Markdown
# Architecture
|
|
|
|
## Server
|
|
|
|
Elysia.js on Bun. All API routes are in `src/app.ts` as `createApp()` — testable via `app.handle(request)` without starting a server. `src/index.tsx` adds Vite middleware (dev) or static serving (prod) and calls `.listen()`. `src/serve.ts` is the dev entry point (dynamic import workaround for Bun EADDRINUSE race).
|
|
|
|
## Database
|
|
|
|
PostgreSQL via Prisma v6. Client generated to `./generated/prisma` (gitignored — run `bun run db:generate` after checkout or schema changes).
|
|
|
|
**Schema models:** `User`, `Session`, `App`, `Log`, `Bug`, `BugImage`, `BugLog`
|
|
|
|
**Enums:** `Role` (ADMIN, DEVELOPER), `BugStatus` (OPEN, ON_HOLD, IN_PROGRESS, RESOLVED, RELEASED, CLOSED), `BugSource` (QC, SYSTEM, USER), `LogType` (CREATE, UPDATE, DELETE, LOGIN, LOGOUT)
|
|
|
|
Import the singleton: `import { prisma } from './lib/db'`
|
|
|
|
## Auth & Roles
|
|
|
|
Session-based auth with HttpOnly cookies stored in the DB (24h expiry). Two roles: `DEVELOPER` (super admin) and `ADMIN`. Users listed in `SUPER_ADMIN_EMAIL` env var are auto-promoted to DEVELOPER on login.
|
|
|
|
Endpoints: `POST /api/auth/login`, `POST /api/auth/logout`, `GET /api/auth/session`
|
|
|
|
Auth state on the frontend is managed via `useSession()` / `useLogin()` / `useLogout()` in `src/frontend/hooks/useAuth.ts` (TanStack Query).
|
|
|
|
## Frontend
|
|
|
|
React 19 + Vite 8 (middleware mode in dev). TanStack Router with file-based routing in `src/frontend/routes/`. All routes are wrapped in `DashboardLayout` from `src/frontend/components/DashboardLayout.tsx`.
|
|
|
|
**Route structure:**
|
|
- `/` → redirect
|
|
- `/login` → login page
|
|
- `/dashboard` → stats overview
|
|
- `/apps` → app list
|
|
- `/apps/$appId` → per-app layout with nested routes: `index`, `errors`, `logs`, `users`, `villages`, `orders`, `products`, `payments`
|
|
- `/users` → operator management
|
|
- `/logs` → system activity log
|
|
- `/bug-reports` → cross-app bug reports
|
|
- `/profile` → user profile
|
|
|
|
**App configs** are defined in `src/frontend/config/appMenus.ts` — each app has an ID and a menu list. Currently active: `desa-plus`. Add new app entries here to register them.
|
|
|
|
**routeTree.gen.ts** is auto-generated by the TanStack Router Vite plugin — never edit it manually.
|
|
|
|
**UI:** Mantine v8, dark theme forced (`#242424`). Charts use `@mantine/charts` (recharts under the hood). Icons from `react-icons/tb`.
|
|
|
|
## API Structure
|
|
|
|
All API routes live in `src/app.ts`. Key groups:
|
|
- `/api/auth/*` — authentication
|
|
- `/api/dashboard/*` — stats and recent errors
|
|
- `/api/apps`, `/api/apps/:appId` — app listing and detail
|
|
- `/api/bugs`, `/api/bugs/:id/status`, `/api/bugs/:id/feedback` — bug report CRUD
|
|
- `/api/operators`, `/api/operators/:id` — user management
|
|
- `/api/logs` — system activity log
|
|
- `/api/system/status` — health check with DB connectivity
|
|
|
|
## Logging
|
|
|
|
`createSystemLog(userId, type, message)` from `src/lib/logger.ts` writes to the `Log` model. Call it for any significant user action (login/logout/CRUD). Logging errors are swallowed so they never break the main flow.
|
|
|
|
## Environment Variables
|
|
|
|
Required: `DATABASE_URL`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`
|
|
Optional: `PORT` (default 3000), `NODE_ENV`, `REACT_EDITOR`, `SUPER_ADMIN_EMAIL` (comma-separated)
|
|
|
|
Validated at startup in `src/lib/env.ts` — missing required vars throw immediately.
|