wireguard-ui/AGENTS.md

# Agent Instructions

Read `WORKSPACE_MEMORY.md` before making structural changes to page code.

## Stack

- **Runtime:** Bun — not Node. Use `bun` commands, never `npm`/`npx`.
- **Framework:** `@moduletrace/bunext` — not Next.js. Routing is filesystem-based under `src/pages/`, served by `Bun.serve` in `src/server.ts`.
- **Database:** `@moduletrace/bun-sqlite` — MariaDB database. Schema in `db/schema.ts`, generated types in `db/types/db.ts`. Config in `bun-sqlite.config.ts` (DB name `rpe.db` in `./db`).
- **UI:** Tailwind CSS v4 + local `twui` components (`src/components/twui`) + shadcn/ui (`src/components/ui`). shadcn/ui configured via `components.json` (style: `radix-vega`), CSS entry at `src/components/twui/base.css` (imported by `src/styles/globals.css`). Uses `@shadcnblocks` registry for extra blocks (`src/components/shadcnblocks`).
- **Icons:** `lucide-react`.
- **Validation:** `zod` v4 (`[email protected]`).

## MCP Tool Usage Guidelines

When building, refactoring, styling, or auditing UI components and layouts, actively invoke these configured MCP servers:

### 1. `design-mcp` (UI/UX Engineering & Design Standards)

- **When to call:** Before constructing new page layouts, design systems, empty/loading states, or interactive UI flows.
- **Instruction:** Query `design-mcp` to ensure accessibility (a11y), proper layout hierarchy, visual balance, and consistent interaction patterns across application workflows.

### 2. `design-systems` (Design System Specs & Reference Patterns)

- **When to call:** When creating or extending reusable component interfaces, verifying design token structures, or inspecting component composition patterns.
- **Instruction:** Query `design-systems` to pull canonical UI patterns, atomic component guidelines, and standard prop naming conventions before creating custom components.

## Entrypoint

`src/server.ts` — runs `bunextInit()`, initializes a persistent **Piper TTS daemon** (global `PIPER_MANAGER`), starts `Bun.serve` with WebSocket upgrade on `/ws`, then starts cron.

## Commands

| Purpose                    | Command                                                   |
| -------------------------- | --------------------------------------------------------- |
| Dev server                 | `bun run dev` (runs `bun src/server.ts`)                  |
| Production                 | `bun run start` (`NODE_ENV=production bun src/server.ts`) |
| Type-check only            | `bunx tsc --noEmit`                                       |
| DB schema (tables)         | `bun run db:schema`                                       |
| DB schema (+vectors)       | `bun run db:schema:vector`                                |
| DB admin UI                | `bun run db:admin`                                        |
| DB backup                  | `bun run db:backup`                                       |
| Port SQLite → MariaDB      | `bun run db:port-sqlite`                                  |
| Install (private registry) | `bun install` (uses registry in `bunfig.toml`)            |

No linter or formatter configured. Type-check is the primary verification step. 33 project-level `.test.ts`/`.test.tsx` files exist but no test runner script is configured — run individual tests with `bun test <file>`.

## Architecture

### Root Component & Context

`src/pages/__root.tsx` — sets up:

- Layout selection (admin/auth/public)
- WebSocket connection via `useWebSocket` + `useWebSocketEventHandler`
- `AppContext` (React context) providing `AppContextType` globally — includes user data, WebSocket, and `sendWebsocketData`
- Server-navigated URL push via `server:navigate-to-url` WebSocket event

## Path Alias

`@/*` resolves from repo root. Import like `@/src/components/ui/button`, `@/db/types/db`, `@/external/cloudflare/r2`.

## Admin Route Hierarchy

Two tiers of admin pages:

- **`/admin/*`** — Resident-facing features: access booking (`/admin/access`), payments (`/admin/payments/*`), chat (`/admin/chat/*`), dependants (`/admin/dependants`), notifications (`/admin/notification`), events (`/admin/events`), settings/profile, support/complaints. Additional sections: `association/`, `devops/`, `management/`, `workers/`
- **`/admin/admin/*`** — Admin-only features: user management (`/admin/admin/users/*`), payment schemes, payment management, documents/constitution, chat group management. Requires `admin` or `exco` role.
- **`/admin/security/*`** — Security features: gate control, guest access monitoring, dependant verification. Requires `security`, `exco`, `manager`, or `aco` role.

Admin sidebar navigation data in `src/layouts/admin/(data)/`. ElevenLabs voice agent widget integrated into admin layout (`src/layouts/admin/(partials)/eleven-labs-widget.tsx`).

## Page Directory Rules

For route-local code under `src/pages`, use non-routed meta folders:

- `(sections)` — page sections
- `(partials)` — components used by sections
- `(data)` — page-local data
- `(functions)` — page-local functions
- `(utils)` — page-local utilities
- `(hooks)` — page-local hooks

Keep route files (e.g. `index.tsx`) thin — compose from route-local meta folders.

Dynamic routes use `[param]` syntax (e.g. `[id]`, `[user_type]`, `[key]`). Catch-all routes use `[[...paths]]`.

Server functions use `index.server.ts` alongside `index.tsx` (e.g. `single-document/[id]/index.server.ts`).

## Shared Code Organization

- **`src/hooks/`** — Shared React hooks: `use-admin-crud-get`, `use-all-users-list-init`, `use-annual-dues-status`, `useAppContext`, `use-fetch-get`, `use-form-init`, `useLocalUser`, `use-mobile`, `use-payments-query`, `use-users-get`
- **`src/functions/`** — Shared functions split by target:
    - `src/functions/backend/` — Server-only: DB queries (`grab-users` in `backend/db/`), email client, RAG ingest, media upload, embed/face ingest
    - `src/functions/frontend/` — Client-safe: CRUD handlers, fetch handlers, Paystack script loader, URL parser
    - `src/functions/general/` — Platform-agnostic: join builders in `general/joins/` (users, payments, guests, messages, chat groups)
- **`src/utils/`** — Utility modules: auth, cookies, crypto, CSRF, hashing, contact classification, RAG text chunking, user type parsing. Most have corresponding `.test.ts` files (auth, cookies, crypto, CSRF, hashing, contact classification, user type parsing).
- **`src/dict/`** — Dictionaries/constants: user types, access codes, gates, LLM providers/models, TTS voices, WebSocket rooms, messaging types, localStorage keys
- **`src/data/`** — Static data: `app-data.ts` (app constants — cookie names, limits, default models, Paystack endpoint), location data, super admin users, role documentation
- **`src/types/`** — Type definitions (~1,350 lines total across 4 files): `index.ts` (1,037 lines), `sql-joins.ts`, `paystack.ts`, `search-api.ts`
- **`src/lib/`** — `utils.ts` exports `cn()` (clsx + tailwind-merge), used by shadcn/ui components
- **`src/scripts/`** — Seed scripts for location and resident data

## Component Systems

| Directory                      | Description                                                                                                                                                                                                                             |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `src/components/twui/`         | Local design system — publishable package with its own `package.json`. Contains elements, composites, editors (TinyMCE), form components, MDX support, hooks, layout, SVGs, and utilities                                               |
| `src/components/general/`      | Shared page components: AI chat, date-picker, logo, Paystack widgets, status-tag, user-avatar, face-search-card, guarantor-preview-modal, guarantor-info-row, etc. (search-select lives in `src/components/twui/form/SearchSelect.tsx`) |
| `src/components/pages/`        | Public page components: `about/`, `constitution/`, `homepage/`                                                                                                                                                                          |
| `src/components/shadcnblocks/` | Components from shadcnblocks.com registry (logo)                                                                                                                                                                                        |

## Conventions

- Prefer one function/component per file over monolithic files with multiple exports.
- **Modularization is non-negotiable: prioritize modularization over monolithic functions/components.** Repeated UI blocks must be extracted into their own reusable components driven by props (e.g. an info row component taking `{ icon, text }`), never repeated inline markup.
- **Every rendered array must have a separate component for each array item.** Always extract the item JSX into its own component and render it via `items.map((item) => <ItemComponent {...item} />)` — never inline the item's JSX inside the map callback.
- Always use object parameters (`{ foo, bar }`) instead of comma-separated positional parameters.
- Prefer existing patterns over new abstractions.
- `.env` is gitignored but exists locally with secrets. Do not commit it.
- `secrets/` directory is also gitignored.
- `external/` binary directories (`**/models`, `**/bin`, `**/x-86`, `**/arm-64`) are gitignored.
- The `bunext.config.ts` excludes `onnxruntime-node` and `@xenova/transformers` from SSR/page compilation (native modules that must stay server-side).
- `tsconfig.json` excludes `src/components/twui/mdx`, `src/components/twui/elements/RemoteCodeBlock.tsx`, and `src/components/twui/mdx/markdown/MarkdownEditorPreviewComponent.tsx` from type-checking.

## Conventions

- Prefer one function/component per file over monolithic files with multiple exports.
- **Modularization is non-negotiable: prioritize modularization over monolithic functions/components.** Repeated UI blocks must be extracted into their own reusable components driven by props (e.g. an info row component taking `{ icon, text }`), never repeated inline markup.
- **UNCHANGEABLE RULE — twui components always win over raw JSX elements.** ALWAYS use twui components (`H1`–`H5`, `P`, `Span`, `List`, `Img`, `Row`, `Stack`, `Container`, `Section`, `Border`, `Card`, `Button`, `Tag`, `Link`, etc.) before basic JSX elements (`<h1>`–`<h6>`, `<p>`, `<span>`, `<ul>`, `<li>`, `<img>`, `<a>`, `<button>`, `<div>`-as-card, etc.). Never introduce or reintroduce a raw JSX element where a twui equivalent exists. Override twui defaults via `className` (e.g. `mb-0!`) rather than reaching for the raw element.
- **UNCHANGEABLE RULE — twui components are preferred over shadcn/ui components.** Use twui before `src/components/ui/*` (shadcn) whenever a twui equivalent exists. The long-term goal is to phase out shadcn/ui entirely — do not introduce new shadcn usage where twui covers the need, and prefer migrating existing shadcn call sites to twui when touching them anyway.
- **LIMIT EDITS TO `src/components/twui/`** — it is a general, publishable library shared across projects (its own `package.json`), not scoped to this repo. Do not modify its components unless strictly necessary. Customize/appearance overrides for this project belong in `src/styles/globals.css` (e.g. tweaking `.twui-card`, `--color-*` tokens, font/type styles) rather than editing twui source files.