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 — hexagonal architecture
│
├── main.py             Compat shim → entrypoints.api.create_app()
├── llm_proxy/main.py   Compat shim → entrypoints.services.llm_proxy
│
├── api/                HTTP layer: thin route handlers, no business logic
│   ├── routes.py       Assembles all routers under /api (alias: /v1)
│   ├── dependencies/   container, current_user, request_context
│   └── routers/        auth, health, projects, repositories, scans,
│                       findings, artifacts, billing, github, git_upload,
│                       api_keys, users, sessions, operations
│
├── application/        Business logic: use-case classes with Command/Result types
│   ├── projects/       Workspace project and repository use cases
│   ├── ingest/         Repository ingest pipeline use cases
│   ├── scans/          Scan lifecycle use cases
│   ├── findings/       Finding queries, mutations, upsert, verification
│   ├── artifacts/      Artifact CRUD, downloads, manifests
│   ├── billing_policy/ Eligibility, reservations, settlement, scan keys
│   └── operations/     Maintenance use cases
│
├── domain/             Pure Pydantic models, state machines, value objects
│   ├── base.py         DomainModel (Pydantic v2 base, extra="ignore")
│   ├── ids.py          Typed domain ID types
│   ├── projects/       WorkspaceProject record
│   ├── repositories/   Repository record + state machine
│   ├── ingest/         IngestJob + SourceSnapshot records + state machine
│   ├── scans/          ScanRecord + state machine
│   ├── findings/       FindingRecord
│   ├── artifacts/      ArtifactRecord + object ref
│   ├── events/         DomainEvent record
│   ├── billing/        Billing domain models
│   └── identity/       CurrentUser, groups, roles
│
├── ports/              Python Protocol interfaces (no implementations)
│
├── adapters/           Concrete implementations of ports
│   ├── engine/vega_core/   VegaCoreEngineAdapter, LocalVegaCoreService, EngineEventSink
│   ├── events/             JsonEventStore, PostgresEventStore
│   ├── identity/           LocalIdentityAdapter, CognitoIdentityAdapter
│   ├── integrations/       GitHubAppAdapter, StripePaymentAdapter, Sub2APIBillingAdapter
│   ├── logging/            LocalAgentLogSink, S3AgentLogSink
│   ├── objects/            LocalObjectStorage, S3ObjectStorage + STS credentials
│   ├── operations/         InMemoryWorkerHeartbeatAdapter, CloudWatchWorkerHeartbeatAdapter
│   ├── queues/             LocalScanQueue, SQSScanQueue, LocalIngestQueue, SQSIngestQueue
│   ├── runners/            LocalScanRunnerLauncher, ECSScanRunnerLauncher,
│   │                       LocalIngestRunnerLauncher, ECSIngestRunnerLauncher
│   └── storage/            JsonRecordStore, InMemoryRecordStore, PostgresRecordStore
│
├── composition/        Wiring layer: adapters → ports → use cases → RuntimeContainer
│   ├── container/      RuntimeContainer definition
│   ├── settings/       RuntimeSettings (VEGA_* env vars + profile defaults + Secrets Manager)
│   └── wiring/         build_api_runtime(), build_scan_runner_runtime(), etc.
│
├── entrypoints/        Process entry points
│   ├── api/            create_app(), lifespan, CORS, JSON middleware
│   ├── workers/        scan_worker.py, repo_ingest_worker.py (polling loops)
│   ├── runners/        scan_runner.py, repo_ingest_runner.py (one-shot executions)
│   ├── maintenance/    reconcile.py, cleanup.py
│   └── services/llm_proxy/  LLM proxy FastAPI app + token management
│
└── storage/migrations/ 001–028 SQL migration files

frontend/               React 18 + Vite + Tailwind + Cognito dashboard

vega-core/              Scan engine submodule (Python library)
├── orchestrator/       stage_orchestrator, scan_workflow
├── stages/             plan, threat_model, audit, verify, patch
├── agents/             Codex runner integration
├── plugins/builtin/    default, linux, web_application plugins
├── framework/          Core abstractions
├── events/             VegaCoreEvent types and emitter
└── artifacts/          Artifact store and layout

scripts/                Runnable entry points
├── run-scan-worker.py            Long-running scan queue consumer
├── run-scan-runner.py            One-shot scan phase executor
├── run-repo-ingest-worker.py     Long-running ingest queue consumer
├── run-repo-ingest-runner.py     One-shot ingest executor
├── run-repo-ingest-dispatcher.py Ingest job dispatcher
├── run-db-migrations.py          Applies SQL migrations
├── run-maintenance.py            Cleanup and reconcile tasks
├── build-codex-runner-image.sh   Builds local Codex Docker image
└── aws/                          Build, push, deploy, migrate, smoke test scripts

docker/                 One Dockerfile per service role
├── api/Dockerfile
├── worker/Dockerfile
├── vega-core-runner/Dockerfile
├── repo-ingest-worker/Dockerfile
├── repo-ingest-runner/Dockerfile
├── llm-proxy/Dockerfile
├── maintenance/Dockerfile
└── codex-runner/Dockerfile

infra/terraform/        AWS infrastructure
├── modules/            network, database, ecs_services, cognito, s3, sqs, etc.
└── envs/dev|prod/      Environment-specific composition and variables

tests/
├── api/                Entrypoint smoke tests, route inventory
├── application/        Use-case logic, billing, ingest, settings wiring
└── domain/             Domain boundary validation

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]
        SW[vega-scan-worker]
        IW[vega-repo-ingest-worker]
        Proxy[vega-llm-proxy]
    end

    subgraph runners["Ephemeral runners (ECS RunTask)"]
        SR[vega-scan-runner\none per scan phase]
        IR[vega-repo-ingest-runner\none per ingest]
    end

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

    FE --> CF
    CF --> S3FE
    CF --> API
    API --> PG
    API --> S3SRC
    API --> SQS_S
    API --> SQS_I
    SQS_S --> SW
    SQS_I --> IW
    SW -->|ECS RunTask| SR
    IW -->|ECS RunTask| IR
    SR --> PG
    SR --> S3ART
    SR --> S3SRC
    SR --> Proxy
    IR --> PG
    IR --> S3SRC
    Proxy --> LLM[AI provider]

Key entry points

What you're looking for Where to look
FastAPI application startup app/entrypoints/api/__init__.py
All API routes assembled app/api/routes.py
All configuration and environment variables app/composition/settings/ (RuntimeSettings)
Runtime container wiring (how adapters are chosen) app/composition/wiring/
Scan business logic app/application/scans/
Finding business logic app/application/findings/
Ingest pipeline logic app/application/ingest/
Bridge between backend and vega-core scan engine app/adapters/engine/vega_core/
Scan worker polling loop app/entrypoints/workers/scans.py + scripts/run-scan-worker.py
Scan runner (executes one scan phase) app/entrypoints/runners/scans.py + scripts/run-scan-runner.py
Ingest worker polling loop scripts/run-repo-ingest-worker.py
Ingest runner scripts/run-repo-ingest-runner.py
LLM proxy service app/entrypoints/services/llm_proxy/
React frontend entry frontend/src/App.tsx
Terraform dev environment infra/terraform/envs/dev/main.tf

Suggested reading path