Skip to content

Vega Backend Documentation

Vega is an AI-powered security code scanner. You point it at a source repository, it uses a large language model to audit the code for vulnerabilities, and it surfaces findings in a web dashboard. This documentation covers every piece of the backend system — from how to run it on your laptop to how it deploys on AWS.

What Vega does

A user's workflow looks like this:

  1. Sign in through the web dashboard.
  2. Create a project as a workspace container.
  3. Add a repository — by providing a Git URL, uploading a zip archive, or connecting via the GitHub App.
  4. Wait for ingest — the backend asynchronously clones/extracts the source and creates an immutable snapshot.
  5. Start a scan — the backend queues the work and an isolated runner executes the AI-powered audit using vega-core and Codex.
  6. Watch progress live in the dashboard as the scan engine streams events.
  7. Review findings — the security issues the scan engine discovered, with severity, file location, and evidence.

Who this documentation is for

New developers — Start with Core Architecture to understand how the system fits together, then read Getting Started to run it locally.

Backend contributors — Read Backend Components and Scan Engine for code-level detail on the hexagonal architecture and use-case patterns.

Operators and SREs — Read AWS when deploying, debugging, or operating the production system.

System at a glance

flowchart LR
    User[Dashboard user] --> API[vega-api\nFastAPI]
    API --> PG[(Postgres JSONB)]
    API --> SQ[SQS scan queue]
    API --> IQ[SQS ingest queue]
    SQ --> SW[vega-scan-worker]
    IQ --> IW[vega-repo-ingest-worker]
    SW -->|ECS RunTask| SR[vega-scan-runner]
    IW -->|ECS RunTask| IR[vega-repo-ingest-runner]
    SR --> VC[vega-core\nscan engine]
    VC --> LLM[vega-llm-proxy]
    LLM --> Provider[AI provider]
    SR --> Artifacts[(S3 artifacts)]
    IR --> Source[(S3 source)]

Each box is a separate process. Locally they can run on one machine. In AWS, they are separate ECS containers with isolated permissions.

The backend uses hexagonal architecture: HTTP routes delegate to use-case classes, which depend on port interfaces, which are implemented by adapters (Postgres, S3, SQS, ECS, Cognito, GitHub, Stripe, etc.). The composition layer wires everything together at startup based on VEGA_* environment variables.

Run the docs locally

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
mkdocs serve

Open http://127.0.0.1:8000.