Files

amaliadwiy a0ca6be8e1 docs: split CLAUDE.md into focused reference files

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>

2026-04-24 15:46:18 +08:00

3.2 KiB

Raw Blame History

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.

3.2 KiB Raw Blame History