agentic-orchestrator

Phase 1 horizontal orchestrator. See 02_phase1_horizontal_build_plan.md for the 8-week plan.

Quick start (local dev)

Prereqs: Docker, Python 3.11, Node 20+.

# 1. backend env
cp backend/.env.example backend/.env

# 2. frontend env
cp frontend/.env.example frontend/.env.local

# 3. bring up Postgres + MinIO + backend
make up

# 4. in a second terminal, run the frontend
cd frontend && npm install && npm run dev

# 5. visit http://localhost:3000

Backend lives at http://localhost:8000. Health: GET /health.

Setup (backend dev)

cd backend
python3.11 -m venv .venv
.venv/bin/pip install -e ".[dev,storage,llm,pdf]"
# Install pre-commit hooks so ruff lint+format runs on every commit.
.venv/bin/pre-commit install

After install, every git commit runs ruff check --fix and ruff format on staged files in backend/. Run the same suite manually with:

make lint                      # ruff check + ruff format --check
.venv/bin/pre-commit run --all-files

ruff is pinned to the same version in backend/pyproject.toml ([project.optional-dependencies] dev) and .pre-commit-config.yaml — keep them in sync when bumping.

Project layout

agentic-orchestrator/
├── backend/                 FastAPI app
│   ├── app/                 routers, models, config, db, logging
│   ├── migrations/          raw SQL migrations (no Alembic until needed)
│   ├── tests/               pytest
│   ├── pyproject.toml
│   └── Dockerfile
├── frontend/                Next.js 15 + Tailwind
│   └── src/app/             App Router pages
├── infra/                   deploy configs (nginx, systemd, vercel)
├── docker-compose.yml       local Postgres + MinIO + backend
├── Makefile
├── PROGRESS.md              daily build log
├── LATER.md                 deferred ideas
├── DEPLOY.md                what a human must do to ship
└── CLAUDE.md                stack rules for the AI builder

Stack

Layer	Choice
Backend	Python 3.11 / FastAPI / async SQLAlchemy 2
Frontend	Next.js 15 / Tailwind / shadcn
Orchestration	in-house topological-waves executor (LangGraph deferred to Phase 2)
LLM	Anthropic only — Haiku 4.5 / Sonnet 4.6 / Opus 4.7
State	Postgres (local Docker; Supabase in prod)
Object store	MinIO local / Cloudflare R2 prod
Auth	Supabase magic link (Day 2)
Streaming	SSE

Rules

• Anthropic only. No OpenAI/Gemini/local.
• Web only. Single-user. No fine-tuning.
• Anything off-plan → LATER.md.
• Daily git commits, Conventional Commits.