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

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

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