HIPCTF2/.kilo/plans/899.md

Implementation Plan: Data and run

1. Architectural Reconnaissance

• Codebase style & conventions: npm-workspace TypeScript monorepo with a NestJS 10 backend and Angular 17 standalone frontend. Runtime configuration is validated centrally with Zod in backend/src/config/env.schema.ts and consumed through Nest ConfigService; filesystem paths are normalized with Node path.resolve, and root scripts delegate to workspace scripts. The feature is not already implemented: persistent defaults still point at /data/hipctf, and the root package has no dev script.
• Data Layer: TypeORM with better-sqlite3. DatabaseModule creates the database parent directory before connecting, DatabaseInitService runs migrations and seeds, and uploads are written and served from the configured upload directory. No schema migration is required; this job changes only default filesystem locations and development process orchestration.
• Test Framework & Structure: Jest 29 with ts-jest, configured in tests/jest.config.js as backend and frontend projects. Tests live under dedicated tests/backend and tests/frontend folders and all run from the repository root with npm test. Add only focused configuration/script contract tests; no browser, UI, database file, port, or long-running process is required.
• Required Tools & Dependencies: Existing Node.js/npm workspace tooling, Angular CLI, ts-node, TypeScript, Jest, and better-sqlite3 remain required. Add the root development dependency concurrently (and update package-lock.json) so one root command can supervise both long-running workspaces and propagate shutdown/failure. setup.sh already installs root/workspace dependencies via npm ci; replace its obsolete absolute /data/hipctf/uploads preparation with project-local ./data/uploads preparation. No global CLI or new system package is required.

2. Impacted Files

• To Modify:
  • backend/src/config/env.schema.ts — change validated DATABASE_PATH and UPLOAD_DIR defaults to ./data/db.sqlite and ./data/uploads.
  • backend/src/database/database.module.ts — align the ConfigService.get database fallback with the canonical project-local database default.
  • backend/src/database/database-init.service.ts — align getDbPath() fallback with the canonical project-local database default.
  • backend/src/main.ts — align startup upload-directory fallback with the canonical project-local upload default.
  • backend/src/modules/uploads/uploads.controller.ts — align upload controller fallback with the project-local upload default.
  • backend/src/common/utils/upload.ts — align Multer destination fallback with the project-local upload default.
  • backend/src/frontend/uploads-static.middleware.ts — align static-upload middleware fallback with the project-local upload default.
  • package.json — add root dev orchestration for backend and frontend and retain start:dev as a compatible alias if desired.
  • package-lock.json — lock the new process-runner dependency and root package metadata.
  • setup.sh — create ./data/uploads relative to the repository root instead of /data/hipctf/uploads, while retaining dependency installation and builds.
  • .gitignore — ignore the root runtime data/ directory rather than the unrelated backend/data/ path, preventing local database/uploads from entering source control.
  • tests/backend/env-schema.spec.ts — assert the exact project-local data defaults returned by the Zod schema.
• To Create:
  • tests/backend/root-dev-script.spec.ts — focused static contract test for root development orchestration and both workspace targets.

3. Proposed Changes

1. Database / Schema Migration:
   • Do not add a TypeORM migration or alter tables. Update the canonical default database location from /data/hipctf/db.sqlite to ./data/db.sqlite.
   • Replace every hard-coded database fallback outside the schema with the same value so direct/unit construction cannot silently revert to /data when configuration is absent.
   • Preserve environment overrides such as DATABASE_PATH=:memory: in tests and custom deployment paths; only defaults change.
2. Backend Logic & APIs:
   • Change the canonical default upload location from /data/hipctf/uploads to ./data/uploads in the environment schema and every defensive ConfigService.get fallback used by startup, upload handling, Multer storage, and static serving.
   • Continue resolving relative paths through path.resolve; when launched through the root scripts, ./data resolves from the project root. Preserve recursive directory creation in DatabaseModule, main.ts, upload helpers, and middleware.
   • Update setup.sh to derive/use the repository-local data directory and create data/uploads, avoiding writes to the container’s shared /data volume for normal application defaults. Keep setup idempotent.
   • Update .gitignore for /data/ so generated SQLite and uploaded files remain local runtime artifacts.
   • Add concurrently as a root development dependency and define npm run dev to launch npm --workspace backend run start:dev and npm --workspace frontend run start in parallel, with clear process names and kill-on-peer-failure/shutdown behavior. Point the existing root start:dev script at npm run dev to avoid two conflicting development entry points.
3. Frontend UI Integration:
   • No Angular source or API URL changes are needed. The Angular dev server remains on port 4200 while the Nest API remains on port 3000; both become available from one root command.
   • Because the frontend uses relative /api and /uploads URLs and no Angular dev-server proxy is currently configured, add a development proxy configuration (and reference it from Angular’s serve target) routing /api and /uploads to http://localhost:3000. This makes the concurrently started frontend functional rather than merely starting two disconnected processes, including credentialed API calls and SSE streams.

4. Test Strategy

• Target Unit Test File: Extend tests/backend/env-schema.spec.ts with one success-path assertion that empty input resolves to DATABASE_PATH === './data/db.sqlite' and UPLOAD_DIR === './data/uploads'. Add tests/backend/root-dev-script.spec.ts to read root package.json and frontend/angular.json, asserting that dev invokes both workspace development commands and the Angular development serve target references the backend proxy. Both tests execute through the existing single root npm test command.
• Mocking Strategy: No external boundaries need heavy mocks. Parse checked-in JSON directly with Node filesystem APIs; do not spawn npm run dev, bind ports, launch Angular/Nest, touch /data, or create persistent files. The environment-schema test calls the pure Zod parser. During implementation, follow Red-Green-Refactor, then verify with npm test, backend/frontend builds, and the repository’s available lint/typecheck commands (no lint script currently exists; the builds provide TypeScript compilation checks).