D3V-Server/AI_CONTEXT.md

# AI Context for D3V-Server

This file is the fast-start map for AI agents working in this repository.
Read this first. Do not scan the entire repo unless the task actually requires it.

## 1. What this project is

`D3V-Server` is a custom fork of Nginx Proxy Manager / xGat3 with an added
WireGuard management module and some project-specific admin features.

Canonical repository:

- `https://src.d3v.ac/d3v/D3V-Server`

Treat that repository as the source of truth for this project.
If another upstream is mentioned, assume it is a historical ancestor or reference,
not the primary project remote, unless the task says otherwise.

At a high level:

- `backend/` is the API server and system orchestration layer.
- `frontend/` is the admin web UI.
- `docker/` is the production runtime assembly.
- `test/` contains Cypress and API-spec checks.
- `docs/` is a separate VitePress docs site.

The production app is not "just backend" or "just frontend":
Docker assembles the backend and the prebuilt frontend into one image.

## 2. Repo map

```text
D3V-Server/
|- backend/              Node.js + Express API, DB, WireGuard logic
|  |- routes/            REST endpoints
|  |- internal/          background/system services
|  |- models/            Objection models
|  |- migrations/        Knex migrations
|  |- schema/            API schema compilation
|  |- templates/         config/template generation
|  |- app.js             Express app wiring
|  `- index.js           backend startup entry
|- frontend/             React + TypeScript + Vite SPA
|  |- src/
|  |  |- pages/          top-level screens
|  |  |- components/     shared UI
|  |  |- hooks/          data and UI hooks
|  |  |- api/            backend API wrappers
|  |  |- modals/         modal flows
|  |  |- context/        auth/theme/locale providers
|  |  |- Router.tsx      route table
|  |  `- main.tsx        frontend entry
|  `- vite.config.ts     dev/build config
|- docker/               production image and runtime scripts
|- docs/                 VitePress docs site
|- test/                 Cypress E2E and swagger lint
|- scripts/              helper scripts
|- install.sh            install/update/reset automation for deployment
`- README.md             user-facing overview
```

## 3. Runtime architecture

```mermaid
flowchart LR
    A["Browser"] --> B["Frontend SPA<br/>frontend/src/main.tsx"]
    B --> C["React Router + pages<br/>frontend/src/Router.tsx"]
    C --> D["Backend API<br/>backend/app.js"]
    D --> E["Route handlers<br/>backend/routes/*"]
    E --> F["Models / DB<br/>Knex + Objection"]
    D --> G["Internal services<br/>backend/internal/*"]
    G --> H["WireGuard CLI / system state"]
    I["docker/Dockerfile"] --> D
    I --> B
```

## 4. First files to open for orientation

If a new session needs project understanding, open these files in order:

1. `AI_CONTEXT.md`
2. `README.md`
3. `backend/index.js`
4. `backend/app.js`
5. `backend/routes/main.js`
6. `frontend/src/main.tsx`
7. `frontend/src/App.tsx`
8. `frontend/src/Router.tsx`
9. `docker/Dockerfile`
10. the relevant package manifest for the area being changed

That is usually enough to understand the system without scanning everything.

## 5. How the backend starts

Main entry: `backend/index.js`

Startup flow:

1. Run DB migrations via `migrateUp()`
2. Run setup/bootstrap via `setup()`
3. Compile/load schema via `getCompiledSchema()`
4. Optionally fetch IP ranges
5. Start timers for internal certificate/IP-range jobs
6. If `WG_ENABLED != false`, start WireGuard service hooks
7. Start Express server on port `3000`

Important implication:

- Many issues that look like "API bugs" can actually come from startup/setup/migration state.
- WireGuard startup failure is logged, but the backend may continue without WireGuard functionality.

## 6. How the backend is organized

Core files:

- `backend/index.js`: process startup and shutdown
- `backend/app.js`: Express middleware, helmet, rate limit, auth, route mounting
- `backend/routes/main.js`: root API router
- `backend/db.js`: DB handle creation
- `backend/lib/config.js`: database/config/env resolution
- `backend/setup.js`: instance bootstrap/setup flow

Important route groups from `backend/routes/main.js`:

- `/api/schema`
- `/api/tokens`
- `/api/users`
- `/api/audit-log`
- `/api/reports`
- `/api/settings`
- `/api/version`
- `/api/nginx/proxy-hosts`
- `/api/nginx/redirection-hosts`
- `/api/nginx/dead-hosts`
- `/api/nginx/streams`
- `/api/nginx/access-lists`
- `/api/nginx/certificates`
- `/api/wireguard`
- `/api/database`

Public WireGuard portal:

- `backend/app.js` mounts `wg_public` before JWT middleware at `/wg-public`
- frontend has a dedicated route branch for `/wg-public`

## 7. How the frontend is organized

Entry path:

- `frontend/src/main.tsx` -> `frontend/src/App.tsx` -> `frontend/src/Router.tsx`

Frontend routing model:

- `Router.tsx` checks health/setup/auth before rendering the main app
- `/wg-public/*` bypasses the standard authenticated admin shell
- most admin pages are lazy-loaded from `frontend/src/pages/*`

Useful places by task:

- New screen or route: `frontend/src/Router.tsx` and `frontend/src/pages/`
- Backend API bindings: `frontend/src/api/`
- Server state/query logic: `frontend/src/hooks/`
- Shared app state: `frontend/src/context/`
- Reusable UI: `frontend/src/components/`
- Modal workflows: `frontend/src/modals/`

## 8. Build, test, lint commands

This repo is multi-package. There is no obvious root workspace command.
Run commands in the relevant subdirectory.

### Backend

Working directory: `backend/`

- `yarn lint`
- `yarn prettier`
- `yarn validate-schema`
- `yarn regenerate-config`
- likely local start: `node index.js`

### Frontend

Working directory: `frontend/`

- `yarn dev`
- `yarn build`
- `yarn lint`
- `yarn preview`
- `yarn test`
- `yarn locale-extract`
- `yarn locale-compile`
- `yarn locale-sort`

### Docs

Working directory: `docs/`

- `yarn dev`
- `yarn build`
- `yarn preview`

### Test

Working directory: `test/`

- `yarn cypress`
- `yarn cypress:headless`
- `yarn cypress:dev`
- `yarn swagger-lint`

### Full build

The production Docker build expects the frontend to be built first.

Common flow:

1. build frontend in `frontend/`
2. build image with `docker/Dockerfile`

Helper script:

- `scripts/build-project.sh`

## 9. Key technologies

- Backend: Node.js, Express 5, Knex, Objection, AJV
- Databases: SQLite by default, MySQL/Postgres supported
- Frontend: React, TypeScript, Vite, React Router, TanStack Query, Tabler UI
- Testing: Vitest for frontend, Cypress for E2E
- Packaging/runtime: Docker, nginx, s6 overlay
- System integration: WireGuard CLI tools inside the container/runtime

## 10. Configuration model

The backend resolves configuration in this order:

1. JSON config file from `NODE_CONFIG_DIR` / `config/*.json`
2. environment variables
3. SQLite fallback using `/data/database.sqlite`

Important file:

- `backend/lib/config.js`

Notes:

- JWT keys are persisted to `/data/keys.json`
- default DB fallback is SQLite
- production behavior often depends on mounted volumes and env vars, not just source code

## 11. WireGuard-specific map

When the task is specifically about WireGuard, start here:

- `backend/internal/wireguard.js`
- `backend/routes/wireguard.js`
- `backend/routes/wg_public.js`
- `frontend/src/pages/WireGuard/`
- `frontend/src/api/backend/wireguard.ts`
- `frontend/src/hooks/useWireGuard.ts`
- relevant migration files in `backend/migrations/`

Operational assumptions:

- `WG_ENABLED` controls whether WireGuard startup hooks run
- runtime requires container/network capabilities such as `NET_ADMIN`
- some behavior only makes sense inside the Dockerized runtime

## 12. Production packaging model

Production image definition:

- `docker/Dockerfile`

Important facts:

- it copies `backend/` into `/app`
- it copies `frontend/dist` into `/app/frontend`
- it installs runtime dependencies inside the image
- it relies on s6-overlay and rootfs scripts

This means:

- frontend must be built before image build
- Docker/runtime files are part of app behavior, not just deployment plumbing

## 13. Known gotchas

- `docker/Dockerfile` assumes `frontend/dist` already exists
- several scripts are shell-oriented and may be awkward on native Windows
- docs and names are inherited from upstream in places, so naming is mixed:
  `nginx-proxy-manager`, `xGat3`, `D3V-Server`, `D3V-NPMWG`
- `README.md` currently has encoding artifacts; do not assume every displayed character is trustworthy
- backend package has no clear `start` script, so use `backend/index.js` as the canonical runtime entry
- do not treat this as a simple SPA-only repo or API-only repo; the Docker assembly matters

## 14. Change strategy for AI agents

When handling a task:

1. Read this file
2. Open only the subsystem entry files for the relevant area
3. Avoid broad repo scans unless the task is cross-cutting
4. Verify whether the change affects Docker/runtime assumptions
5. If the task touches WireGuard, include container/runtime implications in reasoning

Open only what you need:

- backend bug: `backend/index.js`, `backend/app.js`, matching route/service/model files
- frontend bug: `frontend/src/main.tsx`, `App.tsx`, `Router.tsx`, matching page/hook/api files
- build/deploy bug: `docker/Dockerfile`, `scripts/build-project.sh`, `install.sh`
- auth/setup issue: `backend/setup.js`, `backend/routes/tokens.js`, `frontend/src/context/`

## 15. Fast summary

If you only remember one thing:

`D3V-Server` is a Docker-assembled full-stack app where:

- backend runs the API and system logic
- frontend is a Vite React admin UI
- WireGuard is an integrated subsystem, not a separate service
- Docker/runtime files are part of the product behavior
- `backend/index.js`, `backend/app.js`, `backend/routes/main.js`,
  `frontend/src/main.tsx`, `frontend/src/App.tsx`,
  `frontend/src/Router.tsx`, and `docker/Dockerfile` are the core orientation files