Skip to content

development.md

Latest commit

 

History

History
157 lines (115 loc) · 3.86 KB

development.md

File metadata and controls

157 lines (115 loc) · 3.86 KB

Development and maintenance

Run the full stack

From the repository root:

docker compose up -d --build

Check containers:

docker compose ps

Stop the stack:

docker compose down

Rebuild after source changes:

docker compose up -d --build

Health checks

curl http://localhost:3000/api/healthz
curl http://localhost:8081/health
curl http://localhost:8082/health
curl http://localhost:8083/health
curl http://localhost:8084/health
curl http://localhost:8085/health

The orchestrator health endpoint is internal by default. From inside the Docker network it exposes:

GET /healthz
GET /api/healthz

Swagger/OpenAPI

Use service Swagger pages for service-level debugging:

  • Service A: http://localhost:8081/swagger
  • Service C: http://localhost:8082/swagger
  • Service D: http://localhost:8083/swagger
  • Service E: http://localhost:8084/swagger
  • Service F: http://localhost:8085/swagger

The UI API itself is an Express gateway and does not currently expose a dedicated Swagger page.

Frontend and UI API workspace

The UI workspace is located at:

docker-analyzer-ui/

Available scripts from docker-analyzer-ui/package.json:

pnpm build
pnpm typecheck
pnpm start
pnpm dev:frontend
pnpm dev:api

Package layout:

docker-analyzer-ui/artifacts/docker-analyzer   # React frontend
docker-analyzer-ui/artifacts/api-server        # Express UI API

For local development outside Docker, the UI API still needs the backend services to be reachable through the same service URLs expected by the gateway.

Backend service layout

The backend services are under services/:

ServiceA-Templates       # .NET templates and CWE catalog
ServiceB-Orchestrator    # Node.js pipeline orchestrator
ServiceC-Readiness       # .NET readiness checks
ServiceD-ScanRaw         # .NET raw scanner
ServiceE-cwe-resolver    # .NET CWE resolver and cache
ServiceF-FinalReport     # .NET final read-only report
Shared.Contracts         # shared .NET helpers

Most .NET services follow a layered layout:

Api
Application
Domain
Infrastructure

Service B follows a compact Node.js layout:

src/app.ts
src/index.ts
src/routes/
src/lib/

Common debugging workflow

  1. Check the UI health endpoint.
  2. Check service Swagger pages.
  3. Check docker compose ps for unhealthy containers.
  4. Check logs for the UI API and orchestrator first.
  5. If scan execution fails, inspect Service C readiness and Service D logs.
  6. If CWE mapping fails, inspect Service E logs and cache state.
  7. If the report page fails after a completed run, inspect Service F logs and the request manifest.

Useful commands:

docker compose logs -f docker-analyzer-ui
docker compose logs -f docker-analyzer-orchestrator
docker compose logs -f servicec-readiness
docker compose logs -f service-d-scan-raw
docker compose logs -f servicee-cwe-resolver
docker compose logs -f service-f-final-report

Request ID rules

request_id must be safe for filesystem usage. The shared validator allows typical numeric, UUID-like, ULID-like, and slug-like values, but rejects whitespace, path separators, .., and overly long identifiers.

Adding functionality safely

When extending the project, keep the current separation intact:

  • UI pages and hooks stay in the React package.
  • Browser-facing routes stay under the Express UI API /api namespace.
  • Pipeline sequencing belongs to the orchestrator.
  • Template and CWE catalog logic belongs to Service A.
  • Readiness logic belongs to Service C.
  • Raw scan logic belongs to Service D.
  • CWE enrichment and cache logic belongs to Service E.
  • Final report aggregation belongs to Service F.
  • Cross-service filesystem and manifest rules belong to Shared.Contracts.

Avoid bypassing the UI API from the browser, because the current frontend is built around /api/... routes.