Full index of every document in this repository. The architecture chapters are the canonical source for how the system is built; audits explain why a contract has the shape it does; planning notes capture what was scoped, considered, and dropped during the hackathon. Demo and hackathon material live alongside for completeness.
For the project pitch, the rubric, and the three-minute demo storyline, jump to the PRD. For the running system, the main README has the quickstart.
- Project README — what ARIA is, quickstart, stack, daily make targets.
- Product Requirements Document — the problem, the rubric, the three-minute demo storyline.
- Roadmap — milestone-by-milestone delivery plan.
The architecture chapters are written so the executive summary plus the topology diagram of each one is enough to understand the system end to end without reading code.
- Data layer — agent-facing JSONB columns, Pydantic mirrors, the integrity guards behind every write.
- MCP server — the 16 read tools and 1 write tool that are the agents' only path to data.
- KB Builder — PDF vision extraction and the four-question onboarding dialogue that hybridises manual and operator knowledge.
- Sentinel and Investigator — 30-second breach detection plus the RCA loop with extended thinking and the failure-history memory.
- Work Order Generator and Q&A — structured work order output and the operator chat with agent-as-tool handoffs.
- Forecast-watch — predictive alerting before threshold crossings, plus server-side enrichment of the
render_pattern_matchartifact. - Managed Agents — hosted agent loop, hosted MCP, hosted session memory, sandboxed Python container.
- Simulators — Markov state machine, composable signal behaviors, scenario-as-configuration, demo vs realtime modes.
- Operational data and KPIs — TimescaleDB hypertables and OEE / MTBF / MTTR / downtime / quality math.
- Cross-cutting concerns — WebSocket frame catalogue, auth, ContextVar-driven turn ids, shared helpers.
- Architecture decisions — the non-obvious choices and why they were made.
Pre- and post-implementation technical reviews. Each audit was written before merging the corresponding milestone and re-read after to confirm the shipped code matched the intent. Read these to understand why a contract has the shape it does — every quirk in the codebase has a paragraph in one of these documents.
- M2 — MCP Server audit — review of the 17-tool surface against M3-M5 consumers.
- M3 — KB Builder audit — PDF extraction shape, onboarding dialogue, threshold-key integrity.
- M4-M5 — Sentinel / Investigator / Work Order / Q&A audit — pre-implementation review of the agent-loop safety nets and contract.
- M4-M5 — Per-issue context pass — issue-level cross-pass against the codebase.
- M5 — Managed Agents refactor audit — the audit that drove the M5.4 → M5.5 pivot from Q&A to Investigator on Managed Agents.
- M5.5 — End-to-end test report — full live-test report with the seven cascade fixes that landed during the migration.
- M9 — Frontend pre-demo audit — final-stretch review of the operator UI against the demo storyline.
The hackathon was sliced into milestones M1 through M10. Each milestone has an issues.md capturing the scope as filed on the project board; M9 has supplementary design and strategy docs because that milestone fanned out across several concerns.
- Roadmap — the master view: what ships in each milestone, what depends on what.
- M1 — Data layer — schema and Pydantic mirrors.
- M2 — MCP server — the 17-tool catalogue.
- M3 — KB Builder — PDF onboarding agent.
- M4 — Sentinel + Investigator — anomaly detection and RCA loop.
- M5 — Work Order + Q&A — work order generation and operator chat.
- M5.5 — Managed Agents refactor — the post-M5 pivot to hosted infrastructure.
- M6 — Frontend foundation — design system and app shell.
- M7 — Control Room and backend wire — animated P&ID, KPI surfaces, chat wiring.
- M8 — Agentic Workspace — the nine generative-UI artifacts.
- M9 — Polish and E2E — final-stretch demo polish.
- M10 — Submission — submission package and deadline checklist.
- Win plan (J-2 battle plan) — strategic audit and prioritisation 48 hours before submission.
- Demo build spec — authoritative storyboard and technical contracts for the three-minute video.
- Demo plant design — the bottled-water line scenario, machine-by-machine.
- Demo seed content — KB blobs, human context, history rows seeded into the database.
- Wow-factor ideas — visual moments shortlisted for the demo.
- Competitive analysis vs CrossBeam — comparison against the previous hackathon winner.
- Demo submission checklist — the living checklist for the submission package.
- Demo script (v6) — voice-over and storyboard for the three-minute video.
- Design system — visual language, motion grammar, component tokens.
- Hackathon overview — the Built with Opus 4.7 event description.
- Participant rules and resources — submission rules, Discord, judging criteria.
| If you are | Read in this order |
|---|---|
| New to the project | Main README → PRD → Architecture index |
| Tracing "anomaly to RCA" in code | Data layer → MCP server → Sentinel and Investigator |
| Working on the operator UI | Cross-cutting concerns → Frontend design system |
| Adding a new MCP tool | MCP server → Architecture decisions |
| Adding a new agent | Sentinel and Investigator → Architecture decisions |
| Understanding the Managed Agents path | Managed Agents → M5 audit → M5.5 test report |
| Modifying simulator scenarios or KPIs | Simulators → Operational data and KPIs |
| Preparing or reviewing the demo | Demo checklist → Demo script → Demo build spec |