Skip to content

System Map

Use this page when you need to find the file that owns a behavior, or when you want a quick orientation to the repository before reading the detailed sections.

Repository layout

app/                  FastAPI backend — API routes, domain services, storage adapters
│
├── api/              HTTP route handlers (thin — they call services and return models)
├── auth/             Login, tokens, Cognito JWT validation, current-user dependency
├── projects/         The core domain: projects, repos, scans, findings, v16 adapter
├── storage/          Postgres store, S3 client, archive safety, SQL migrations
├── queues/           SQS scan queue producer/consumer
├── llm_proxy/        AI provider proxy with per-scan usage enforcement
├── sessions/         Legacy upload/analyze flow (still exists, not the current path)
├── events/           Append-only event persistence
├── api_keys/         Programmatic API key management
├── billing/          Usage summary (placeholder)
├── hardening/        Quotas, worker heartbeats, stale-scan cleanup
└── core/             Settings (env vars), structured errors, JSON logging

frontend/             React + Vite + Tailwind dashboard

v16/                  Scan engine submodule
├── adapter.py        The scan API the backend calls
└── codex_runner.py   Codex CLI orchestration and streaming

scripts/              Runnable entry points
├── run-scan-worker.py        Claims queued scans from SQS
├── run-scan-runner.py        Runs one claimed scan (what the ECS runner task runs)
├── run-db-migrations.py      Applies SQL migrations
├── run-maintenance.py        Cleanup and maintenance jobs
├── build-codex-runner-image.sh  Builds the local Codex Docker image
└── aws/              AWS deployment helpers (build, push, deploy, migrate, smoke test)

docker/               One Dockerfile per service role
infra/terraform/      AWS infrastructure
├── modules/          Reusable building blocks (network, database, ECS services, etc.)
└── envs/dev|prod/    Environment composition and variables

tests/                Pytest suite
data/                 Local development state (JSON files, snapshots, artifacts)

How the runtime fits together

flowchart TD
    subgraph browser["Browser"]
        FE[React dashboard]
    end

    subgraph aws_edge["Edge (AWS)"]
        CF[CloudFront CDN]
        S3FE[S3 frontend bucket]
    end

    subgraph app_layer["Application layer (ECS Fargate)"]
        API[vega-api\nFastAPI]
        Worker[vega-worker]
        Proxy[vega-llm-proxy]
    end

    subgraph scan_layer["Scan execution (ECS RunTask)"]
        Runner[vega-v16-runner\none task per scan]
    end

    subgraph data_layer["Data layer"]
        PG[(Postgres)]
        S3SRC[S3 source bucket]
        S3ART[S3 artifacts bucket]
        SQS[SQS scan queue]
    end

    FE --> CF
    CF --> S3FE
    CF --> API
    API --> PG
    API --> S3SRC
    API --> SQS
    SQS --> Worker
    Worker --> Runner
    Runner --> PG
    Runner --> S3SRC
    Runner --> S3ART
    Runner --> Proxy
    Proxy --> LLM[AI provider]

Key entry points

What you're looking for Where to look
FastAPI application startup app/main.py
All API routes assembled app/api/routes.py
All configuration and environment variables app/core/settings.py
Project, scan, and finding business logic app/projects/service.py
Bridge between backend and v16 scan engine app/projects/v16_adapter.py
Worker process (claims scans from SQS) scripts/run-scan-worker.py
Runner process (executes one scan) scripts/run-scan-runner.py
LLM proxy service app/llm_proxy/main.py
React frontend entry frontend/src/App.tsx
Terraform dev environment infra/terraform/envs/dev/main.tf

Suggested reading path