d3v/D3V-Server
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
D3V-Server/AI_CONTEXT.md

9.7 KiB
Raw Blame History

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/xtcnet/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