- Drop unused email module and media text extraction path
- Remove 12 unused dependencies
- Remove unused imports in server.ts
- Add typecheck and test scripts
- Rewrite AGENTS.md to describe this project
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Read `WORKSPACE_MEMORY.md` before making structural changes to page code.
WireGuard UI — a self-hosted web admin for WireGuard hosts and clients. The app runs **as root** and executes system commands (`wg`, `ip`, `iptables`, `wg-quick`, firewall managers). Treat every API route and every value that reaches a shell or a WireGuard config as security-sensitive.
## 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`).
- **Database:** `@moduletrace/bun-sqlite` — SQLite. Schema in `db/schema.ts`, generated types in `db/types/db.ts`. Config in `bun-sqlite.config.ts` (DB name `wgui` in `./db`). Import its types from `@moduletrace/bun-sqlite/types` (not`/dist/types`).
- **UI:** Tailwind CSS v4 + local `twui` components (`src/components/twui`). Global styles in `src/styles/main.css`.
@@ -27,48 +26,35 @@ When building, refactoring, styling, or auditing UI components and layouts, acti
## 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.
`src/server.ts` — runs `bunextInit()`, starts `Bun.serve` on `0.0.0.0` (port from `SiteData.ServerPort`), serves `/media/*` via `handleMediaServer`, then runs `syncWireguardHosts()` to bring host tunnels in line with the DB.
On-disk state: WireGuard keys/configs/iptables scripts live under `/var/lib/wgui` (`grabDirNames()` in `src/utils/grab-dir-names.ts`); uploaded media under `DATA_DIR` (default `./.data`).
| Dev server | `bun run dev` (runs `sudo bun src/server.ts`) |
| Production | `bun run start` |
| Build | `bun run build` |
| Type-check | `bun run typecheck`(`bunx tsc --noEmit`) |
| Tests | `bun run test` (`bun test`) |
| DB schema | `bun run db:schema` |
| DB admin UI | `bun run db:admin` |
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>`.
No linter or formatter configured. Type-check and `bun test` are the verification steps.
## 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
-`src/pages/__root.tsx` — picks the layout (`src/layouts/main` or `src/layouts/admin`, or `LoginShell` for auth pages) and provides `AppContext`.
- **API:** `src/pages/api/admin/*` (host/client setup, network info, firewall status, service restart/update, media), generic CRUD at `src/pages/api/admin/crud/[[...paths]].ts` with per-table handlers in `crud/(tables)/<table>/{get,post,put,del}.ts`, plus `api/auth/login.ts` and `api/create-first-user.ts`.
- **Every `/api/admin/*` route must authenticate** — nothing guards the prefix globally. Use `adminApiGuard({ req })` (`src/functions/backend/auth/admin-api-guard.ts`) or `userAuth` + `checkUserAccess`.
-**Shell safety:** never interpolate request/DB values into `execSync` strings. Use `execFileSync` with an args array or `node:fs` APIs, and validate values before they reach a WireGuard config (newlines there can inject `PostUp` commands). Validators live in `src/utils/` (`validate-ipv4`, `validate-ipv4-cidr`, `validate-allowed-ips`, `validate-endpoint-host`, `validate-interface-name`).
## Path Alias
`@/*` resolves from repo root. Import like `@/src/components/ui/button`, `@/db/types/db`, `@/external/cloudflare/r2`.
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`).
`@/*` resolves from repo root. Import like `@/src/components/general/admin-card`, `@/db/types/db`.
## Page Directory Rules
@@ -89,45 +75,24 @@ Server functions use `index.server.ts` alongside `index.tsx` (e.g. `single-docum
- **`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/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) |
- **`src/components/general/`** — Shared app components (admin cards/buttons, clients table, host IP field, login shell, user form).
## 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.
- **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/main.css` (e.g. tweaking `.twui-card`, `--color-*` tokens, font/type styles) rather than editing twui source files.
- **twui `Input`/`Textarea`: prefer `defaultValue` over `value`.** The component manages internal state and patches the DOM directly (`src/components/twui/form/Input/index.tsx`), so `value` is not a true controlled prop — a static `value` gets reverted on every re-render, wiping in-progress edits. `value` only works well when the parent updates it on each change (live display), not for pre-filling an editable field. Use `defaultValue` to pre-fill editable inputs; `onChange`/`changeHandler` still fire.
-`.env` is gitignored but exists locally. Do not commit it.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Claude Opus 5.5