Skip to content

Known Gaps

This page tracks documentation and structural gaps that affect onboarding or operations. These are things that are missing or inconsistent that a new contributor or operator would reasonably expect to find.

Missing DESIGN.md

README.md references DESIGN.md for the Deep Field design system, but the file doesn't exist in the repository. Until it's created, the frontend design system is undocumented. Options:

  • Add DESIGN.md with component guidelines and usage patterns
  • Or update the README to remove the reference and point to component files directly

Legacy sessions coexisting with the current flow

The repository has two parallel workflows: - Current: Projects → Repositories → Scans → Findings (the primary path) - Legacy: Sessions (/v1/sessions/*) — an older upload/analyze flow

Both work, but new contributors may be confused about which one to extend. The legacy path should either be formally deprecated (with a timeline for removal) or documented as "kept for backward compatibility — do not build new features on it."

aws.md as overlapping source material

aws.md in the main repository is a comprehensive (1000+ line) AWS runbook. This documentation site now covers the same material in a more structured, task-oriented format. Until aws.md is retired or reduced to a high-level reference, there's a risk that the two diverge.

Recommendation: keep aws.md as historical source material and consider adding a header that redirects readers to this documentation site.

No committed OpenAPI artifact

The API schema can be generated from any running server instance (curl http://localhost:8000/openapi.json) but no committed openapi.json exists in the repository. This means:

  • Client generators in CI/CD need a running server to export the schema
  • There's no easy way to review API contract changes in a PR

Recommendation: add a CI step that generates and commits (or artifact-stores) openapi.json as part of the build. Or use python -c "from app.main import app; import json; print(json.dumps(app.openapi()))" in CI to validate it.

No automated end-to-end scan test

The smoke test checks API health. There is no automated test that: 1. Creates a repository 2. Ingests source 3. Runs a scan to completion 4. Verifies findings exist

This means a broken scan pipeline might not be caught until a human tries to run a scan manually after deployment.