Documentation Index
Triple-axis table of contents for the AlphaSwarm docs.
Two entry points:
- Humans → architecture.md
- AI agents → ../AGENTS.md
Both link back here.
Canonical runtime surfaces (May 2026)
| 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 | alpha-swarm.ai green-lane validation + switch + rollback |
| Deployment artifacts | ../alphaswarm_platform/deployments/README.md | active | Compose + Kubernetes manifests for current architecture |
| Operator UI | ../alphaswarm_client/README.md | active | Vite frontend is the primary UI |
| AlphaSwarm IDE | alphaswarm-ide.md | active | Theia 1.72 + 6 AlphaSwarm extensions + research copilot + notebook |
| Knowledge Base | knowledge-base.md | active | alphaswarm_kb boundary — KBRuntime + KBCorpusSpec + adapter trinity (HierarchicalRAG default, Cognee / Graphiti / Mem0 opt-in) + 4-scope KBLayerComposer + hybrid OpenFGA + OPA policy stack |
| KB federation gateway | kb-federation.md | active | alphaswarm_kb_federation — cross-silo marketplace recall reverse-proxy |
| AlphaSwarm IDE roadmap | alphaswarm-ide-roadmap.md | active | Phased plan (Phase A shipped; B + C trigger-driven) |
| AlphaSwarm IDE CLI entrypoint | ../alphaswarm_cli/docs/index.md | active | alphaswarm-cli ide is the canonical IDE entrypoint |
| Repository split map | repository-split.md | migration | Domain boundaries for future standalone repositories |
| Monorepo path contract | alphaswarm-monorepo-paths.md | active | Canonical paths for cross-repo references |
| Code index governance | code-index-governance.md | active | Agent search/index workflow across split boundaries |
| Legacy Next.js UI | webui.md | rollback | Keep only for emergency rollback context |
| Legacy Solara UI | ../alphaswarm/ui/ | rollback | Deprecated runtime surface |
| Legacy k8s manifests | ../alphaswarm_platform/deploy/k8s/README.md | legacy | Historical manifests; do not use for new rollouts |
| 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 and human
- ../README.md — what AlphaSwarm is, screenshots, release notes.
- architecture.md — system map + request lifecycle.
- ../CONTRIBUTING.md — set up the dev environment.
- glossary.md — terms used everywhere.
- Pick a subsystem from the table 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.
- ../.cursor/rules/ — glob-scoped rule files.
- 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 (table below).
- (Cross-session work) ../.agents/state-template.md.
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.md | 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 | Future repository/domain boundary map |
| code-index-governance.md | Agent search and code-index rules |
Data plane
| Doc | Purpose |
|---|---|
| data-plane.md | Provider → cache → DuckDB view pipeline |
| data-catalog.md | Iceberg catalog + ingest pipeline |
| data-self-service.md | Master narrative for the four-phase self-service data fabric expansion |
| datasets-catalog.md | Kedro-style BaseDataset abstraction (data fabric phase 0) |
| metadata-cache.md | Redis prefetch cache backing every entity dropdown (data fabric phase 0) |
| data-discovery.md | Active discovery browser unifying ingested + uningested catalog entries (data fabric phase 1) |
| airbyte-builder.md | Schema-driven Airbyte connector builder + AlphaSwarm Fetcher codegen (data fabric phase 2) |
| dagster-sandbox.md | Ephemeral interactive Dagster + Airbyte sandbox console (data fabric phase 3) |
| visualization-layer.md | Trino-backed Superset and Bokeh exploration layer |
| pgvector-control-plane.md | pgvector control plane — data.vector.* MCP tools + PgVector dataset kind + alembic 0045 (Phase 3 refactor) |
| codebase-mcp.md | Codebase MCP server — agent view of the AlphaSwarm source tree via codebase.* tools (Phase 2 refactor) |
| sera.md | SERA (Ai2 Open Coding Agents) as an opt-in LLM provider for the codebase MCP elaborator (Phase 2.5 refactor) |
| analytics-frontend.md | Interactive analytics in the Vite frontend — QuantStats tearsheets / rolling / underwater / drawdown / ML overlays (Phase 4 refactor) |
| agent-watchdog.md | Agent stall watchdog Celery beat task + GET /agents/health + data.agents.health MCP tool (Phase 5 refactor) |
| alpha-vantage.md | AV provider quota + cache |
| streaming.md | Kafka topic taxonomy + ingester layout |
| live-market.md | Live subscription + WebSocket relay |
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 | Initial MLOps service — agent-facing interfaces, lifecycle handlers, MLSkill spec/runtime, OOD rules, dedicated alphaswarm-ml-mcp server |
| backtest-engines.md | Engine catalogue + invariants (vbt-pro primary, event-driven, ZVT, AAT, fallback) |
| vbtpro-integration.md | Deep vectorbt-pro integration: modes, hooks, agent + ML components, 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 | Lucic-Tse 2024-2026 portfolio-level options market making |
| microstructure-toxicity.md | Toxicity regime detection + agent-driven YAML mutation loop |
| strategy-lifecycle.md | draft → backtested → paper → live |
| strategy-browser.md | Data-browser → strategy spec UX |
Agentic
| Doc | Purpose |
|---|---|
| agentic-development.md | AlphaSwarm's spec-pattern as the agentic-coder skill-artifact equivalent + consolidated ADLC security manifesto |
| multi-agent-patterns.md | Sequential / Parallel / Debate / Coordinator / ReAct topologies mapped to alphaswarm/agents/graph/ + the seven orchestration adapter topologies |
| workflow-studio.md | Additive orchestration control plane — WorkflowSpec + WorkflowRuntime + seven adapters + replayable runs |
| orchestration-refactor-rollout.md | Operator rollout / rollback runbook for every ALPHASWARM_ORCHESTRATION_* flag |
| agentic-pipeline.md | Crew control plane |
| providers.md | LLM provider registry + tier routing |
Trading + operations
| Doc | Purpose |
|---|---|
| paper-trading.md | Session loop + risk model |
| paper-metadata-gate.md | Strict startup metadata validation + operator runbook |
| bots.md | Bot entity (TradingBot / ResearchBot), graphical builder, deployment |
| observability.md | OTEL → Jaeger + structured logs |
| ../alphaswarm_client/README.md | Active Vite frontend route/model overview |
| webui.md | Legacy Next.js page tree (rollback only) |
Latest changes
| Doc | Last touched |
|---|---|
| data-catalog.md | Persistent host warehouse + Director |
| glossary.md | New (covers Director, Iceberg conventions, tiers) |
| architecture.md | New (replaces README ASCII art) |
| erd.md | New (per-domain ERDs across 110+ tables) |
| class-diagram.md | New (5 hierarchies) |
| data-dictionary.md | New (15 sections) |
| flows.md | New (5 flows) |
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 repo paths from the doc:
[alphaswarm/data/pipelines/director.py](../alphaswarm/data/pipelines/director.py). 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.