Documentation Index
The map for the AlphaSwarm docs. Pick your entry point:
Three entry points:
- New or non-technical readers → What is AlphaSwarm?
- Engineers → Architecture
- AI agents → AGENTS.md
All link back here.
Current deployment version:
0.1.0-alpha.1— the shipped Kubernetes / topology label (AGENTS hard rule 65). Package versions on individual sibling repos may differ. Details: Release notes.
How the docs are organized
The site follows the Diátaxis layout — knowing which section you're in tells you what kind of page to expect:
| Section | Question it answers | Character |
|---|---|---|
| Get started | "Where do I begin?" | Orientation: overview, quickstart, glossary, conventions |
| Tutorials | "Teach me by doing" | Runnable, learning-oriented walkthroughs |
| How-to | "How do I accomplish X?" | Task recipes, operations guides, runbooks |
| Concepts | "How does X work and why?" | Explanations of the systems |
| Reference | "What exactly is the contract?" | APIs, Python packages, data dictionary |
| Architecture | "What was decided and why?" | ADRs, RFCs, plans, safety runbooks |
| Changelog | "What changed recently?" | Dated engineering changes + recently-added docs |
What's new (August 2026)
The July–August development push is summarized in the 2026-08-13 changelog. New concept pages:
| Topic | Page |
|---|---|
| Honest promotion statistics (trial ledger, evidence bundle) | Promotion evidence |
| HITL approvals + TTL expiry | Approval queues |
| Order-latency measurement | Six-clock latency |
| Vendor-agnostic market data + BYOK | Market-data vendors |
| Kafka schema + addressing governance | Streaming governance |
| Named business metrics (in development) | dbt semantic layer |
| Interactive Dagster sandbox isolation | Dagster sandbox |
| Production Dagster Definitions + instance config | Dagster operations |
| First-class module program (ADRs 033–039) | Transformation plan |
Canonical runtime surfaces
| Surface | Canonical path | Status | Notes |
|---|---|---|---|
| Local setup + run | operations/local-setup.md | active | Default entry point for local development |
| Kubernetes rollout | operations/kubernetes-deploy.md | active | Production-oriented deployment path |
| Tower 2-node rollout | operations/tower-cluster-deploy.md | active | Dedicated tower+laptop target bootstrap path |
| AlphaSwarm blue/green cutover | operations/alphaswarm-fund-blue-green-cutover.md | active | Green-lane validation + switch + rollback |
| Deployment artifacts | alphaswarm_platform/deployments | active | Compose + Kubernetes manifests in the sibling alphaswarm_platform repo |
| Operator UI | alphaswarm_client README | active | Vite frontend is the primary UI (sibling repo) |
| AlphaSwarm IDE | alphaswarm-ide.md | active | Theia-based IDE + AlphaSwarm extensions + research copilot |
| Knowledge Base | knowledge-base.md | active | alphaswarm_kb boundary — KBRuntime + adapter trinity + 4-scope KBLayerComposer |
| KB federation gateway | kb-federation.md | active | Cross-silo marketplace recall reverse-proxy |
| First-class module transformation | transformation plan | phase 1 landed | Public domain/application kernel facade (ADRs 033–039) |
| Sibling-repo path contract | alphaswarm-monorepo-paths.md | active | Canonical paths across sibling repositories |
| Code index governance | code-index-governance.md | active | Agent search/index workflow across split boundaries |
| Repository split map | repository-split.md | executed | Domain boundaries for standalone sibling repositories |
| Legacy Next.js UI | webui.md | rollback | Keep only for emergency rollback context |
| Archived planning/audit docs | archive/README.md | archive | Historical context only; not operational guidance |
Operational snippet catalog
Reusable commands that are valid against the current repository layout:
# Generate local config from schema
make generate-config ENV=local
# Start the local workload stack
make dev
# Start the isolated admin/control-plane stack
make dev-admin
# Deploy current dev overlay to Kubernetes
make deploy-k8s ENV=dev
By audience
I'm new or non-technical
- What is AlphaSwarm? — the platform in plain English: lifecycle, safety model, who does what.
- Glossary — plain-English basics — the trading and platform vocabulary.
- Recently added — what's new on the docs site.
I'm an engineer
- README — what AlphaSwarm is, screenshots, release notes.
- architecture.md — system map + request lifecycle.
- Quickstart — dev stack to green backtest.
- CONTRIBUTING — set up the dev environment.
- glossary.md — terms used everywhere.
- Pick a subsystem from the tables below.
I'm an AI agent
- AGENTS.md — terse rule-set + project map.
- WORKFLOW.md — Plan / Act / Reflect cadence, FAST vs SLOW modes, intervention nodes.
- agentic-development.md — spec-pattern as the AlphaSwarm skill-artifact + ADLC security manifesto.
- glossary.md — definitions.
- erd.md + class-diagram.md — structural maps.
- flows.md — end-to-end sequences.
- repository-split.md + code-index-governance.md — current repo boundary map.
- The relevant subsystem doc (tables below).
By lifecycle stage
By subsystem
Architecture + reference
| Doc | Purpose |
|---|---|
| architecture.md | System component diagram + request lifecycle |
| erd.md | Per-domain entity-relationship diagrams |
| class-diagram.md | Class hierarchies (Symbol, LLMProvider, Strategy, Engines, Pipeline) |
| Data dictionary | Table-by-table column reference |
| flows.md | Sequence diagrams for ingestion / backtest / agents / paper |
| glossary.md | Project-specific terminology |
| domain-model.md | Narrative on the domain types |
| core-types.md | Symbol, enums, dataclasses |
| repository-split.md | Executed sibling-repo / domain boundary map |
| code-index-governance.md | Agent search and code-index rules |
Data plane
| Doc | Purpose |
|---|---|
| market-data-vendors.md | Vendor homes + BYOK credential resolution |
| dagster.md | Production Dagster Definitions, validate gate, two code locations, instance yaml |
| dagster-sandbox.md | Per-session Dagster + Airbyte sandbox isolation |
| streaming-governance.md | Kafka wire framing, schema manifest, catalog-first addressing |
| dbt-semantic-layer.md | Named business metrics catalog (in development) |
| connector-control-plane.md | Governed connector onboarding |
| layer-composition.md | How data layers stack |
| pgvector-control-plane.md | pgvector control plane — data.vector.* MCP tools |
| memory-engines.md | Agent memory backends |
| rag.md | Retrieval-augmented generation baseline |
| research-papers-rag.md | Research-paper corpus + retrieval |
Knowledge base + graph
| Doc | Purpose |
|---|---|
| graph-data-pillar.md | The governed graph plane (ADR 032) |
| knowledge-base.md | alphaswarm_kb boundary + runtime |
| knowledge-graph.md | Graph construction + queries |
| finance-knowledge-graph.md | Finance-domain graph schema |
| bi-temporal-graph.md | Bitemporal vocabulary |
| learning-service.md | Learning-service graph layer |
| kb-runtime.md, kb-permissions.md, kb-federation.md, kb-silo-iac.md | KB runtime, policy, federation, and IaC |
Strategy + ML
| Doc | Purpose |
|---|---|
| analysis-framework.md | Hash-locked AnalysisSpec + AnalysisRuntime umbrella |
| analysis-lab.md | Hybrid /analysis/lab UI (dataset-tabs + XYFlow Composer) |
| analysis-flows.md | Per-flow reference for the analysis catalog |
| factor-research.md | Building factor / alpha strategies |
| ml-framework.md | Train → register → deploy → score |
| ml-libraries.md | Per-library reference (TF/Keras/Prophet/sklearn/PyOD/sktime/HF) |
| ml-alpha-backtest.md | AlphaBacktestExperiment orchestrator + MLAlphaBacktestRun schema |
| ml-flows.md | Lightweight workbench flows catalog |
| ml-preprocessing-pipeline.md | ML preprocessors as data-engine pipeline nodes |
| ml-builder.md | Graphical experiment builder UX |
| ml-testing.md | Interactive ML testing workbench |
| mlops-service.md | MLOps service — lifecycle handlers, MLSkill spec/runtime, alphaswarm-ml-mcp |
| backtest-engines.md | Engine catalogue + invariants (vbt-pro primary, event-driven, ZVT, AAT, fallback) |
| vbtpro-integration.md | Deep vectorbt-pro integration: modes, hooks, walk-forward |
| hft-backtest.md | hftbacktest-driven LOB engine, LobStrategy API, latency / queue models |
| optimal-control.md | JAX-compiled HJB solvers — Avellaneda-Stoikov + Cartea-Jaimungal-Penalva |
| portfolio-options-mm.md | Portfolio-level options market making |
| microstructure-toxicity.md | Toxicity regime detection + agent-driven YAML mutation loop |
| strategy-lifecycle.md | draft → backtested → paper → live |
| promotion-evidence.md | Trial ledger + evidence bundle + gate chain |
| strategy-browser.md | Data-browser → strategy spec UX |
Agentic
| Doc | Purpose |
|---|---|
| agentic-development.md | AlphaSwarm's spec-pattern + consolidated ADLC security manifesto |
| multi-agent-patterns.md | Sequential / Parallel / Debate / Coordinator / ReAct topologies + the seven orchestration adapter topologies |
| workflow-studio.md | Additive orchestration control plane — WorkflowSpec + WorkflowRuntime + replayable runs |
| orchestration-refactor-rollout.md | Operator rollout / rollback runbook for every ALPHASWARM_ORCHESTRATION_* flag |
| agentic-pipeline.md | Crew control plane |
| agents.md | The agent taxonomy |
Trading + operations
| Doc | Purpose |
|---|---|
| paper-trading.md | Session loop + risk model |
| paper-metadata-gate.md | Strict startup metadata validation + operator runbook |
| approval-queues.md | HITL approval queues + TTL expiry |
| bots.md | Bot entity (TradingBot / ResearchBot), graphical builder, deployment |
| observability.md | OTEL → Jaeger + structured logs |
| six-clock-latency.md | Order-latency clocks + Grafana dashboard |
| webui.md | Legacy Next.js page tree (rollback only) |
Doc conventions
- Mermaid is the diagram format. GitHub renders it natively. Don't commit PNG/SVG diagrams unless they're irreplaceable.
- Cross-link with relative markdown paths (for example,
bar.md) so the navigation works on GitHub and locally. - Cite code with full GitHub URLs
(
https://github.com/Alpha-Swarm-ai/alphaswarm/blob/main/...). Don't link to specific line numbers (they bit-rot fast). - Keep it short — narrative goes in subsystem docs, definitions in glossary.md, structure in erd.md / class-diagram.md. Don't repeat yourself.
- Start with plain English — every concept page opens with a paragraph a non-specialist can follow before diving into mechanism.