AI Implementation feature(899): Data and run (#39)

2026-07-22 19:56:33 +00:00
parent 113dd47371
commit 1a40e5708a
23 changed files with 305 additions and 53 deletions
@@ -0,0 +1,119 @@
+---
+type: guide
+title: Local Development Workflow
+description: How to run the backend and frontend together in development, including the root dev script, Angular dev-server proxy, and project-local data directory.
+tags: [guide, dev, dev-server, proxy, concurrently, setup, tester]
+timestamp: 2026-07-22T19:54:00Z
+---
+
+# Overview
+
+The HIPCTF monorepo ships a single root command — `npm run dev` — that
+boots the NestJS backend and the Angular dev server in parallel, with
+the Angular dev server proxying `/api` and `/uploads` calls to the
+backend on port 3000. All persistent runtime files (SQLite database,
+uploaded icons / attachments / logos) live under the project-local
+`./data/` directory.
+
+# How to start the full stack (tester steps)
+
+1. From the repository root, install workspace dependencies once:
+   ```
+   npm ci
+   ```
+2. Start both servers in parallel:
+   ```
+   npm run dev
+   ```
+   This uses `concurrently` to run:
+   * `npm --workspace backend run start:dev` (NestJS watch mode on `http://localhost:3000`)
+   * `npm --workspace frontend run start` (Angular dev server on `http://localhost:4200`)
+   Process names `backend` and `frontend` are prefixed per output line.
+   If either process exits with a non-zero status, the other is killed
+   (`--kill-others-on-fail`).
+3. Open the browser:
+   * **Frontend (preferred for app work):** `http://localhost:4200/`
+   * **Backend (single-port mode, serves built SPA later):** `http://localhost:3000/`
+4. To run them individually during debugging:
+   ```
+   npm run dev:backend
+   npm run dev:frontend
+   ```
+
+# Project-local data directory
+
+| Path              | Purpose                                               | Backed by env var   |
+|-------------------|-------------------------------------------------------|---------------------|
+| `./data/`         | Root runtime data directory (gitignored).             | —                   |
+| `./data/db.sqlite`| SQLite database file (created on first boot).         | `DATABASE_PATH`     |
+| `./data/uploads/` | Uploaded category icons, challenge files, site logos. | `UPLOAD_DIR`        |
+
+Both defaults are declared in `backend/src/config/env.schema.ts` and
+re-declared as fallbacks in every backend code path that calls
+`ConfigService.get` so direct/unit construction cannot silently revert
+to the legacy absolute paths. Relative paths are resolved with
+`path.resolve` against the process working directory — when launched
+via the root scripts, that is the repository root.
+
+The legacy absolute defaults (`/data/hipctf/db.sqlite`,
+`/data/hipctf/uploads`) have been removed; set `DATABASE_PATH` and
+`UPLOAD_DIR` explicitly if you need to point at an external location
+(e.g. a mounted volume in production).
+
+The data directory is created automatically:
+* `DatabaseModule` ensures the parent directory of `DATABASE_PATH`
+  exists before connecting.
+* `main.ts`, `UploadsController`, `buildMulter`, and
+  `UploadsStaticMiddleware` all `mkdir -p` the upload directory on
+  startup.
+* `setup.sh` creates `./data/uploads` before any build so first-boot
+  Multer writes never fail.
+
+# Angular dev-server proxy
+
+`frontend/proxy.conf.json` is wired into the `serve` target in
+`frontend/angular.json` so relative URLs from the SPA hit the backend
+without CORS prompts:
+
+| Origin path | Target                  | Notes                                                  |
+|-------------|-------------------------|--------------------------------------------------------|
+| `/api`      | `http://localhost:3000` | All REST controllers + SSE endpoints. `changeOrigin: true`. |
+| `/uploads`  | `http://localhost:3000` | Static files served by `UploadsStaticMiddleware`.      |
+
+The proxy is **development-only.** In production (`npm start` /
+`backend/dist/main.js`) the backend serves the built SPA directly and
+no proxy is involved.
+
+# Root scripts
+
+| Script              | What it does                                                       |
+|---------------------|--------------------------------------------------------------------|
+| `npm run dev`       | Start backend + frontend together via `concurrently`.              |
+| `npm run dev:backend` | Start only the NestJS backend in watch mode.                     |
+| `npm run dev:frontend` | Start only the Angular dev server.                              |
+| `npm start`         | Run the **production** backend (`node backend/dist/main.js`).      |
+| `npm run build`     | Build both workspaces (frontend first, then backend).              |
+| `npm run start:dev` | Alias for `npm run dev` (kept for backwards compatibility).        |
+| `npm test`          | Run the full Jest project (backend + frontend).                    |
+
+# Expected behavior (tester)
+
+* `npm run dev` displays interleaved backend and frontend logs, each
+  prefixed with the process name and a color.
+* The Angular dev server prints `Application bundle generation complete`
+  within a few seconds and the page is reachable at
+  `http://localhost:4200/`.
+* Visiting `http://localhost:4200/` triggers
+  `GET /api/v1/bootstrap` (proxied to port 3000) and shows the
+  appropriate public, login, or bootstrap page.
+* Uploads (e.g. category icons via the admin UI) land under
+  `./data/uploads/` and are immediately readable from the dev frontend
+  via `/uploads/...` (proxied).
+* Pressing `Ctrl+C` once terminates both processes cleanly.
+
+# See also
+
+- [System Overview](/architecture/overview.md)
+- [Database Schema Overview](/database/schema.md)
+- [Uploads Endpoints](/api/uploads.md)
+- [Key Files Index](/architecture/key-files.md)