Visuals · Companion Internal · v2026.05.08 Companion to Project Plan

Maps, flows, and a Gantt.

Visual companion to the project plan — a Gantt of all ten phases, two flow charts (job lifecycle and hybrid retrieval), a system map of every service and how the bytes actually move between them, and a mind map of the repo to keep one's bearings.

Doc kind
Visuals · companion
Pairs with
Project Plan.html
Generated
2026-05-08
Owner
Dave Cockson
§A

Gantt — phases on a calendar

~17 weeks · solo · estimate

Durations are estimates for one operator working part-time. PF is complete; P0 is in flight. The NOW marker sits at the start of week 1 (2026-05-08). Critical-path bars (P3, P4, P7) are drawn in terracotta — slipping these slips the cutover.

Phase
Done In progress Planned Critical path ▎NOW = 2026-05-08
§B

Phase dependency graph

What blocks what

Mostly linear, but P2 (observability) feeds P3 forward (tracing endpoint), and P7 (RAG+KG) collects work from P3 (compose), P5 (web), and P6 (MCP). P9 cutover gates everything that touches the old runner.

PF Pre-flight P0 Foundations P1 Infrastructure P2 Observability P3 Runner core P4 Worker P5 Web + Chat P6 MCP P7 RAG + KG P8 Agents P9 Cutover critical path forward dep linear seq.
Phase DAGSPEC §05 + tasks.md
§C

System map — runtime

Contabo · Davas · Cloud

The runner runs on Contabo behind Cloudflare Tunnel. Davas is a remote Ollama box reached over the same tunnel. Stateful stores (Qdrant, Neo4j, vault) sit beside the workers. Alloy is the only thing that talks outbound to Grafana Cloud.

Contabo VPS · Docker Compose cloudflared control.davidcockson.com web · FastAPI :8000 · HTMX UI · SSE worker poller · executor mcp · FastMCP :8001 · search/fetch/vault/code rag · LangGraph :8002 · hybrid retrieve vault /root/obsidian-vault-v2 queue · filesystem _queue · _active _completed · _failed qdrant :6333 · vault·web·memory neo4j + graphiti :7687 bolt · :7474 http alloy logs · metrics · traces ollama (host) 127.0.0.1:11434 syncthing vault propagation infisical agent prod env · materialised .env sqlite chat history · mounted vol External · Cloud Davas · Ollama davas-ollama.davidcockson.com Grafana Cloud Tempo · Loki · Mimir + alerts Discord job · disk · davas alerts Infisical Cloud (EU) homelab-rebuild · prod AWS S3 · us-east-1 tfstate · vault-snapshots artifacts
Runtime topologySPEC §10 · §11
§D

Flow — job lifecycle

Submit → enqueue → execute → archive

Filesystem is the message queue. Every transition is a single shutil.move — never copy + delete. A 2-second mtime guard tolerates Syncthing partial writes; _active/ is requeued on worker startup so a crash never strands a job.

Submit web · CLI · cron _queue/ YYYY-MM-DD-…md poller.py 2s mtime guard _active/ shutil.move (atomic) executor.py dispatch by type text single call chain multi-step research + MCP tools _completed/ runner-outputs/*.md _failed/ + traceback Discord success · failure worker boot crash recovery requeue _active/ on boot
Job lifecycleSPEC §08
§E

Flow — LangGraph hybrid retrieval

Decompose · parallel · rerank · synthesise

The query splits, fans out to Qdrant and Neo4j in parallel, the merged context is reranked, then a final LLM call synthesises the answer. Nightly cron re-indexes new vault notes into both stores.

Query user · agent decompose subquestions vector_retriever Qdrant · top-N chunks kg_retriever Neo4j · entity neighbourhood rerank combined context synthesise final LLM call ┃ parallel Nightly cron · vault notes → vector_indexer (Qdrant) + kg_indexer (graphiti → Neo4j)
services/rag/graph.pySPEC §09
§F

Flow — provider routing

Davas health-check · no silent fallback

The Davas health-check rule is the one bit of subtle logic in the router: if Davas is unreachable, the UI greys out Davas-routed models, and any submission targeting Davas returns 503 immediately with a clear reason. Never silently fall back.

request model = X target? Ollama · Contabo qwen2.5:14b · always-on Davas reachable? → Davas Ollama 503 immediate no silent fallback cloud · groq · gemini · anthropic 429s logged · timeouts pinned Contabo Davas Cloud yes no
shared/providers/router.pySPEC §06
§G

Flow — secrets at deploy

Infisical · machine identities · compose
Infisical Cloud EU · homelab-rebuild · prod contabo-prod ID Universal Auth · Viewer homelab-prod ID Universal Auth · Viewer infisical run --recursive --env=prod -- <cmd> env injected subfolders flattened docker compose up -d
Secrets pipelineSPEC §11 · run-log 2026-05-08
§H

Mind map — repos & modules

Five repos · the whole tree

Centred on llm-runner. The four sibling repos hand IaC, observability roles, and runbooks to it; everything bottoms out in containerised services.

llm-runner python · the rebuild platform-docs runbooks · dashboards · ADRs infra-contabo terraform + ansible infra-homelab ansible only · proxmox infra-shared docker·tailscale·infisical·alloy tests/ · agents/ mirrors source · 3 agents services/ web · worker · mcp · rag shared/{providers, config, models, observability} runbooks/cutover.md dashboards/*.json backend "s3" · cloudflare DNS firewall · vault-v2 path prod-services VM dev-learning VM roles/ idempotent --check green briefing · daily cron research · scheduled memory · graphiti
Five repos, one centreSPEC §04 · §07
§I

Mind map — the spec, in one glance

17 sections · five clusters
SPEC.md v2026-05-08 Why §01 goals · §02 rules Stack §03 tech · §06 routing Layout §04 repos · §07 modules Runtime §08 queue · §09 KG · §10 compose · §11 env Ops §12 obs · §13 CI/CD · §14 phases Scope & provenance §15 not-building · §16 revisit · §17 changelog
Spec at a glanceSPEC.md table of contents
§J

Cutover — sequence diagram

P9 · seven steps · rollback aware
Old runner Snapshots / S3 New runner P9.1 snapshot vault → S3 P9.2 runbook + rollback P9.3 stop old disable services P9.4 vault path v2 → vault P9.5 monitoring decom + archive P9.6 langfuse teardown P9.7 archive repos old runner offline
P9 sequencetasks.md · P9.1–P9.7
§K

Cost & time — what this build will burn

Tweakable · solo · estimate

Phase durations come from the Gantt; AI-token costs assume a Claude-Code-style pair-programming style at ~tokens-per-hour authored by the assistant. Model mix per phase follows the recommendations in tasks.md: Sonnet by default, Opus on the subtle-logic tasks called out (P1.3, P3.4, P4.1, P6.5, P7.5, P9.2), Haiku for scaffolding (P0.5, P2 dashboards). Open the Tweaks panel (bottom-right) to adjust pace, token rates, infra costs, and Pro cap.

Total assistant tokens
—MTok
across all phases
Est. API cost
$—
if billed à la carte
Est. operator hours
—h
over project span
% Pro weekly cap (peak wk)
—%
peak phase / Pro Sonnet-equiv
Phase Name Weeks Hours Model mix Tokens API $ % Pro / wk
Totals — — — — —
Per-phase breakdown ■ Sonnet · ■ Opus · ■ Haiku
Peak-week Pro burn
—
0%of cap
Sonnet-equivalent tokens during the heaviest phase week.
Average-week Pro burn
—
0%of cap
Average across the build span; useful for steady-state planning.
Monthly burn breakdown
$— / mo · build period
API tokens Contabo S3 Davas elec. Grafana Cloud
Operating cost during the buildExcludes hardware sunk cost
Caveats. These are order-of-magnitude estimates, not invoices.
  • Token rates per provider drift; defaults reflect rough public rates as of May 2026 — override in Tweaks if your numbers differ.
  • Pair-programming token throughput varies wildly by task (refactors burn far more than scaffolds). The default 60k tok/h is mid-range for Claude Code-style sessions.
  • Claude Pro weekly cap is normalised to Sonnet-equivalent tokens. Opus tokens count ~5× toward the cap; Haiku ~⅓×.
  • Infra costs assume eu-west-2 / us-east-1 list prices at solo-scale traffic; Grafana Cloud and Infisical free tiers are assumed unless overridden.
  • Operator hourly rate is set to $0 by default (solo, unpaid). Plug in a benchmark rate to model an opportunity-cost view.