> For the complete documentation index, see [llms.txt](https://docs.alpha-security.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alpha-security.app/architecture/overview.md).

# Overview

Alpha has three components: a collector, a server, and a web UI.

## Collector

A single static Go binary (`al`) that runs on the operator's testing machine. It captures tool output through a PTY and ships it to the server as raw bytes plus metadata (command, cwd, timing, exit code, tags).

The collector is intentionally simple. It does not parse output or understand tool semantics. That's the server's job. This means parsers can evolve and re-run over historical data without re-collection.

The collector also does not modify the command you run. It executes exactly what you typed, with no injected flags or sidecar files. This keeps the tool's footprint identical to running it directly.

## Server

Node.js + Fastify application backed by PostgreSQL. It handles:

* **Ingestion** - Receives raw output from collectors, stores evidence
* **Parsing** - Runs the parser pipeline to extract structured entities from raw output
* **Entity graph** - Maintains the deduplicated entity graph (hosts, services, credentials, etc.)
* **API** - Serves the REST API consumed by the web UI, the collector's `query`/`loot` commands, and third-party tools
* **Auth** - Multi-operator RBAC with MFA support
* **Realtime** - SSE push for live updates in the UI

Migrations run automatically on startup. The server is the only component that talks to Postgres.

## Web UI

React + Vite single-page application. Communicates with the server exclusively through the API. In production, nginx serves the static files and reverse-proxies API requests to the server.

The web UI provides the engagement dashboard, run timeline, entity browser, graph visualization, findings board, report generation, and admin panel.

## How they connect

```
┌──────────────────┐         ┌──────────────────┐
│   Collector(s)   │──HTTP──▶│     Server       │
│   (operator box) │         │  (Fastify + PG)  │
└──────────────────┘         └────────┬─────────┘
                                      │ API
                             ┌────────┴─────────┐
                             │     Web UI        │
                             │  (nginx + React)  │
                             └──────────────────┘
```

In development, Vite's dev proxy handles the API forwarding. In production, nginx does the same thing.

## Engagement scoping

Everything is scoped to an engagement. Each engagement has its own evidence, entities, graph, findings, and reports. Operators are assigned to engagements and can only see data within their assignments (admins see everything).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.alpha-security.app/architecture/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.