System Architecture and Repository Mapping
AlphaSwarm is a hosted, multi-tenant AI/quant platform with separate surfaces for public marketing, authenticated customer operations, staff administration, local power users, IDE workflows, agent execution, data/knowledge services, and model governance.
High-level system design
Runtime service interaction
Repository-to-architecture placement
| Layer | Repositories | Responsibility |
|---|---|---|
| Public and app surfaces | alphaswarm_website, alphaswarm_ui, alphaswarm_client, alphaswarm_admin, alphaswarm_ide | User-facing, staff-facing, local, and developer/IDE entrypoints. |
| Edge and hosted cells | alphaswarm_platform, alphaswarm_api | Tenant router, Envoy/ext_authz posture, hosted deployment manifests, gateway/API composition. |
| Control and execution | alphaswarm_controller, alphaswarm_worker, alphaswarm_orchestration, alphaswarm_cli, alphaswarm_ops_console | Workload lifecycle, worker registration/execution, orchestration adapters, CLI/admin ops. |
| Identity and config | alphaswarm_auth, alphaswarm_config, alphaswarm_core | AuthN/AuthZ, RBAC, device identity, software CA, configuration providers, core contracts. |
| Data and knowledge | alphaswarm_data, alphaswarm_ingest, alphaswarm_catalog, alphaswarm_graph, alphaswarm_kb, alphaswarm_kb_federation, alphaswarm_index, alphaswarm_research | Data acquisition, cataloging, graph sync, RAG/KB, federated retrieval, research plane. |
| Agents and bots | alphaswarm_agents, alphaswarm_assistant, alphaswarm_bots, alphaswarm_mcp | Agent runtime/specs, assistants, bots, MCP integration endpoints. |
| AI/ML lifecycle | alphaswarm_mlops, alphaswarm_models, alphaswarm_eval, alphaswarm_rl, alphaswarm_learning, alphaswarm_viz | Model governance, training/tuning, evaluation, reinforcement learning, continuous learning, visualization. |
| Observability and business ops | alphaswarm_observe, alphaswarm_observe_js, alphaswarm_finops, alphaswarm_docs | Telemetry SDKs/services, frontend telemetry, billing/cost monitoring, documentation. |
Hosted cell and tenancy model
The tenant router in alphaswarm_platform is the hot-path decision service between edge proxying and per-cell services. It validates JWT issuer/audience/expiry against JWKS, rejects unsafe algorithms, resolves tenants/workspaces to deployment cells, and injects verified identity/tenancy headers upstream.
Key boundaries
alphaswarm_apiis a composition/gateway layer and should not absorb privileged deployment logic.alphaswarm_ops_consoleowns operational deployment surfaces separately and uses predeclared argv-only action specs.alphaswarm_authcentralizes identity/provider abstractions, whilealphaswarm_uiis Entra-only for hosted customer login.alphaswarm_mlopsgoverns the ML/LLM/AgentOps plane but does not replace model training libraries or agent business logic.alphaswarm_coreshould remain dependency-light and contract-oriented.