# 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.