Local-first architecture
Understand the AQP control plane and why data, models, and agents default to local execution.
Purpose
Understand the AQP control plane and why data, models, and agents default to local execution.
This guide is part of the Agentic Quant Platform documentation set. The project is a local-first quant research and trading platform with FastAPI, Celery, Postgres, Iceberg, DuckDB, MLflow, Redis-backed RAG, strategy factories, agents, bots, streaming, and paper trading. Use this page when you need enough context to understand the design before changing code, manifests, configuration, or operational runbooks.
Where it fits
Repository: agentic_quant_platform
Audience: builders who want research, data engineering, agent orchestration, and trading operations in one reproducible local lab.
Main technologies: Python, FastAPI, Celery, Redis, Postgres, SQLAlchemy, Alembic, Iceberg, DuckDB, MLflow, LiteLLM, CrewAI, LangGraph, vectorbt-pro, Kafka, Flink, Next.js.
The implementation should be read as a set of boundaries rather than a pile of tools. Configuration declares what should exist, runtime services perform the work, persistence layers keep durable state, and observability explains what happened after the fact.
Implementation pattern
- Identify the durable resource: table, topic, deployment, agent spec, bot spec, manifest, or content page.
- Find the wrapper or runtime responsible for it instead of bypassing the project contract.
- Add configuration in the narrowest location that can express the new behavior.
- Add a smoke test or runbook step that proves the change can be recovered.
- Document the operational owner and the failure mode that matters most.
Operational checks
| Check | Why it matters |
|---|---|
| Configuration is explicit | Rebuilds and restarts should not depend on memory. |
| State has one owner | Competing writers make recovery hard. |
| Logs and progress are visible | Long-running workflows need user trust. |
| Backups or rebuild steps exist | A local-first system still needs disaster recovery. |
| Links to related docs are current | The portal is the public index for the workspace. |
Extension notes
When extending this area, prefer the project's existing factory, registry, wrapper, or runtime pattern. That keeps new work compatible with the surrounding code and avoids a second hidden implementation of the same idea.