Skip to content

Commit d1d3aed

Browse files
zestonesCopilot
zestones
and
Copilot
committed
feat: add comprehensive documentation index and architecture overview to the repository
Co-authored-by: Copilot <copilot@github.com>
1 parent 17c934a commit d1d3aed

2 files changed

Lines changed: 328 additions & 42 deletions

File tree

‎README.md‎

Lines changed: 202 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,90 +1,250 @@
1-
<img src="docs/assets/banner.png" alt="ARIA Logo" class="w-32 mb-4" />
1+
<img src="docs/assets/banner.png" alt="ARIA" />
2+
<br />
23

3-
# ARIA
4+
<div align="center">
45

5-
> Industrial reliability copilot — predictive maintenance, OEE, and shop-floor knowledge surfaced through agents.
6+
[![Docker](https://img.shields.io/badge/Docker-24.0%2B-blue?logo=docker)](https://docs.docker.com/)
7+
[![Python](https://img.shields.io/badge/Python-3.12-blue?logo=python)](https://www.python.org/)
8+
[![React](https://img.shields.io/badge/React-19-blue?logo=react)](https://react.dev/)
9+
[![TimescaleDB](https://img.shields.io/badge/TimescaleDB-PostgreSQL-blue?logo=postgresql)](https://www.timescale.com/)
10+
11+
</div>
12+
13+
> Predictive maintenance that configures itself. Upload a manufacturer's PDF, calibrate with the floor operator and ARIA watches the equipment from there — forecasting drift before it crosses a threshold, opening a work order the moment a real anomaly fires, running root-cause analysis with extended thinking, and answering operator questions in natural language. Generative-UI artifacts (charts, diagnostic cards, work orders) stream into the operator's chat as the agents work.
14+
15+
Built for the **"Build With Opus 4.7"** hackathon. Open source, MIT licensed.
16+
17+
---
18+
19+
## The problem ARIA solves
20+
21+
Configuring predictive maintenance takes 3–6 months and costs €50k–€500k per site. 95% of industrial plants can't afford it. The floor operator already knows when the machine will fail — they hear it. That knowledge never makes it into a system.
22+
23+
**ARIA is the bridge:** manual reader → operator-calibrated KB → multi-agent watcher → work order generator. Six months becomes ten minutes.
24+
25+
---
26+
27+
## What ARIA does
28+
29+
```mermaid
30+
flowchart LR
31+
PDF["PDF manual"] --> KBBuilder["KB Builder"]
32+
Operator["Operator calibration"] --> KBBuilder
33+
KBBuilder --> DB[("KB + failure history")]
34+
35+
Signals["Live signals"] --> Sentinel["Sentinel"]
36+
DB --> Sentinel
37+
Sentinel -- "drift warning" --> UI["Operator UI"]
38+
Sentinel -- "anomaly" --> Investigator["Investigator"]
39+
40+
DB <--> Investigator
41+
Investigator -- "RCA" --> WOG["Work Order Generator"]
42+
WOG --> UI
43+
44+
QA["Q&A"] -- "ask_investigator" --> Investigator
45+
QA --> UI
46+
```
47+
48+
- **KB Builder** — reads the manufacturer PDF with Opus vision, calibrates thresholds with the operator through a short dialogue.
49+
- **Sentinel** — breach detection loop; also runs forecast on signal tails and emits drift warnings before a breach occurs.
50+
- **Investigator** — root-cause analysis with extended thinking + Python sandbox; reads and writes failure history.
51+
- **Work Order Generator** — turns the RCA into actions, parts list, and intervention window.
52+
- **Q&A** — natural-language operator chat; hands off to the Investigator when a deep diagnosis is needed.
53+
54+
---
655

756
## Quickstart
857

58+
Three commands stand the entire stack up:
59+
960
```bash
10-
make install # one-time: backend venv + frontend node_modules on host (for IDE)
11-
make up # docker compose stack with hot reload
61+
cp .env.example .env # fill in ANTHROPIC_API_KEY and JWT_SECRET_KEY
62+
make install # one-time: backend venv + frontend node_modules (for IDE intellisense)
63+
make up # docker compose: db + migrations + 4 simulators + backend + frontend
1264
```
1365

14-
| Service | URL |
15-
|-------------|------------------------------------------------------------------|
16-
| Frontend | [http://localhost:5173](http://localhost:5173) |
17-
| Backend API | [http://localhost:8000](http://localhost:8000) — docs at `/docs` |
66+
Open the operator UI:
1867

19-
Default seed users: `admin/admin123`, `operator/operator123`, `viewer/viewer123`.
68+
| Service | URL | Notes |
69+
|-------------|----------------------------------------------------------|-------------------------|
70+
| Frontend | [http://localhost:5173](http://localhost:5173) | hot module reload |
71+
| Backend API | [http://localhost:8000](http://localhost:8000) | OpenAPI docs at `/docs` |
72+
| Database | `localhost:5432` (`aria` / `aria_dev_password` / `aria`) | TimescaleDB |
2073

21-
## Hot reload
74+
Default seeded users — pick one to log in:
2275

23-
Both backend (`uvicorn --reload`) and frontend (`vite` HMR) bind-mount the source from the host, so any edit triggers an instant reload inside the container — no rebuild needed.
76+
| Username | Password | Role |
77+
|------------|---------------|----------|
78+
| `admin` | `admin123` | admin |
79+
| `operator` | `operator123` | operator |
80+
| `viewer` | `viewer123` | viewer |
2481

25-
## Useful targets
82+
Source is bind-mounted from the host into both backend and frontend containers — every edit reloads instantly without a rebuild.
2683

27-
```bash
28-
make help # full target list
29-
make ps # service status
30-
make logs # tail all logs
31-
make down # stop stack
32-
make e2e # backend smoke test (66 assertions)
33-
34-
make check # all quality gates (CI parity)
35-
make format # auto-format backend (black) + frontend (biome)
36-
make backend.test # pytest unit suite
37-
make db.shell # psql into the database
84+
> [!NOTE]
85+
> The first `make up` builds the simulator, backend, and frontend images. Allow two to three minutes on a cold cache. Subsequent starts are seconds.
86+
87+
---
88+
89+
## How it runs
90+
91+
```mermaid
92+
flowchart LR
93+
Sims["Simulators<br/>(one container per cell)"]
94+
DB[("TimescaleDB<br/>operational hypertables<br/>+ agent state")]
95+
Backend["Backend<br/>FastAPI + 6 agents + MCP server"]
96+
Front["Frontend<br/>operator UI"]
97+
98+
Sims --> DB
99+
Backend <--> DB
100+
Front <-->|"WebSocket + REST"| Backend
38101
```
39102

103+
The simulators write `machine_status`, `production_event`, and `process_signal_data` rows into TimescaleDB at one-Hertz. The backend reads from the same database through a 14-tool MCP surface (the agents' only path to data) and pushes events to the frontend over a WebSocket bus.
104+
105+
Two simulator modes ship out of the box:
106+
107+
- **`SIMULATOR_MODE=realtime`** (default). Cells idle near nominal; drift is barely visible over a thirty-minute rehearsal. Demo endpoints inject scenario spikes on cue.
108+
- **`SIMULATOR_MODE=demo`**. Compresses a seventy-two-hour failure scenario into roughly four minutes wall-clock. The Bottle Filler's bearing-wear vibration crosses the alert threshold on its own — useful for a hands-off rehearsal loop.
109+
110+
The full simulator engine and per-cell scenario walkthrough live in [docs/architecture/08-simulators.md](docs/architecture/08-simulators.md).
111+
112+
---
113+
40114
## Stack
41115

42-
- **Backend** — FastAPI, asyncpg, TimescaleDB / PostgreSQL · black + flake8 + pyright
43-
- **Frontend** — React 19, TypeScript, Vite, Tailwind CSS 4, TanStack Query · Biome
44-
- **Infra** — Docker Compose, GitHub Actions CI
116+
**Backend.** FastAPI on Python 3.12, asyncpg, Pydantic, FastMCP. `black` + `flake8` + `pyright` enforce the contract.
117+
118+
**Database.** TimescaleDB (PostgreSQL with hypertables) for the operational time series. JSONB columns on the agent-facing tables, validated at every write through Pydantic mirrors.
45119

46-
## Managed Agents (Investigator — optional)
120+
**Agents.** Anthropic Python SDK against Claude Opus 4.7 (reasoning + PDF vision) and Sonnet (routine tool work). The Investigator runs on Claude Managed Agents with hosted MCP and a sandboxed Python container; everything else runs on the Messages API.
47121

48-
The Investigator can run on Claude Managed Agents instead of the default Messages API loop. This unlocks hosted MCP (Anthropic calls our endpoint directly) and hosted session persistence (the reasoning trace survives for 30 days). Off by default — flip with a single env var.
122+
**Frontend.** React + TypeScript + Vite, Tailwind, TanStack Query. Biome for lint and format.
49123

50-
### 1. Set the path secret
124+
**Simulators.** Python with asyncpg. One container per monitored cell. Markov state machine plus composable signal behaviors — drift, noise, derived signals, fault triggers — driven entirely by per-scenario configuration.
51125

52-
`/mcp` becomes a public endpoint once it is tunneled. Anthropic's `mcp_servers` config does not forward custom HTTP headers, so the URL itself carries the secret. Generate a 32-byte token and put it in `.env`:
126+
**Infrastructure.** Docker Compose, GitHub Actions CI, optional Cloudflare tunnel for hosted-MCP exposure.
127+
128+
---
129+
130+
## Repository layout
131+
132+
```
133+
ARIA/
134+
├── backend/ FastAPI + agents + MCP server
135+
│ ├── agents/ KB Builder, Sentinel, Forecast, Investigator, WO Generator, Q&A
136+
│ ├── aria_mcp/ FastMCP server — 14 read tools + 1 write tool
137+
│ ├── modules/ Bounded contexts (kb, work_order, signal, kpi, logbook, chat, sandbox, ...)
138+
│ ├── core/ Cross-cutting: ws_manager, thresholds, security, database
139+
│ ├── infrastructure/ SQL migrations + idempotent seeds
140+
│ └── tests/ Unit + integration + e2e smoke
141+
├── frontend/ React app — operator UI
142+
├── simulator/ Standalone Python package — one image, four scenarios
143+
├── docs/ Architecture, audits, planning, demo, PRD
144+
├── docker-compose.yaml
145+
├── Makefile
146+
└── README.md
147+
```
148+
149+
---
150+
151+
## Documentation
152+
153+
> **[Full documentation index →](docs/README.md)**
154+
155+
### Getting started
156+
157+
- [Quickstart](#quickstart) — clone, run, log in.
158+
- [Product framing (PRD)](docs/ARIA_PRD.md) — the problem, the rubric, the three-minute demo storyline.
159+
- [Architecture overview](docs/architecture/README.md) — system diagram, milestone map, conventions.
160+
161+
### Understanding ARIA
162+
163+
- [Data layer](docs/architecture/01-data-layer.md) — agent-facing JSONB columns and Pydantic mirrors.
164+
- [MCP server](docs/architecture/02-mcp-server.md) — the 14 tools the agents use to read the world.
165+
- [KB Builder](docs/architecture/03-kb-builder.md) — PDF vision extraction and the four-question onboarding dialogue.
166+
- [Sentinel and Investigator](docs/architecture/04-sentinel-investigator.md) — anomaly detection and root-cause analysis.
167+
- [Work Order Generator and Q&A](docs/architecture/05-workorder-qa.md) — work order generation and the operator chat.
168+
- [Forecast-watch](docs/architecture/06-forecast-watch.md) — predictive alerting and pattern enrichment.
169+
170+
### Architecture and reference
171+
172+
- [Managed Agents](docs/architecture/07-managed-agents.md) — hosted agent loop, hosted MCP, sandboxed Python container.
173+
- [Simulators](docs/architecture/08-simulators.md) — Markov engine, signal stack, scenarios, demo vs realtime modes.
174+
- [Operational data and KPIs](docs/architecture/09-kpi-and-telemetry.md) — hypertables and OEE / MTBF / MTTR / quality math.
175+
- [Cross-cutting concerns](docs/architecture/cross-cutting.md) — WebSocket frame catalogue, auth, shared helpers.
176+
- [Architecture decisions](docs/architecture/decisions.md) — the non-obvious choices and why they were made.
177+
178+
---
179+
180+
## Development
181+
182+
`make help` prints the full list. The handful you will actually reach for:
53183

54184
```bash
55-
echo "ARIA_MCP_PATH_SECRET=$(openssl rand -hex 32)" >> .env
185+
make up # bring the full stack up (hot-reload on backend + frontend)
186+
make deploy # bring the full stack up with cloudflare tunnel for managed agents
187+
make ps # service status
188+
make logs # tail logs from every container
189+
make down # stop everything (including the tunnel if it is running)
190+
191+
make check # all quality gates (CI parity): black + flake8 + pyright + biome + tsc
192+
make format # auto-format backend (black) + frontend (biome)
193+
make backend.test # pytest unit suite
194+
make e2e # end-to-end backend smoke (requires the stack up)
195+
make doctor # detect dependency drift between manifests and running containers
196+
197+
make db.shell # psql into the database
198+
make db.reset # drop volume and re-run migrations + seeds (destroys data — confirms first)
199+
make db.seed # re-apply the demo seeds idempotently
56200
```
57201

58-
### 2. Expose `/mcp` via Cloudflare Tunnel
202+
---
59203

60-
Two options:
204+
## Hosting the Investigator on Anthropic Managed Agents
61205

62-
**Option A — Persistent tunnel (stable hostname, needs Cloudflare dashboard setup).** Create a tunnel in the Cloudflare Zero Trust dashboard mapping a hostname to `http://backend:8000`, copy the token, then:
206+
The Investigator runs on [Claude Managed Agents](docs/architecture/07-managed-agents.md) with a sandboxed Python container for numerical diagnostics. Falls back to Messages API in under five minutes (`INVESTIGATOR_USE_MANAGED=false`).
207+
208+
**1. Generate a path secret.** Anthropic's `mcp_servers` config does not forward custom HTTP headers, so the URL itself is the bearer token.
209+
210+
```bash
211+
echo "ARIA_MCP_PATH_SECRET=$(openssl rand -hex 32)" >> .env
212+
```
213+
214+
**2. Expose `/mcp` via Cloudflare Tunnel.** Two flavours:
215+
216+
*Persistent tunnel (stable hostname).* Create the tunnel in the Cloudflare Zero Trust dashboard mapping a hostname to `http://backend:8000`, then:
63217

64218
```bash
65219
echo "CF_TUNNEL_TOKEN=<token-from-dashboard>" >> .env
66-
docker compose --profile tunnel up -d tunnel
220+
make up.tunnel
67221
```
68222

69-
**Option B — Quick tunnel (ephemeral URL, no account needed).** Run one-off:
223+
*Quick tunnel (ephemeral URL, no account needed).*
70224

71225
```bash
72226
docker run --rm --network aria_aria cloudflare/cloudflared:latest \
73227
tunnel --url http://backend:8000
74228
```
75229

76-
Either way, copy the tunneled URL and append the path secret — this becomes `ARIA_MCP_PUBLIC_URL`:
230+
Either way, append the path secret to the tunnel URL — that becomes `ARIA_MCP_PUBLIC_URL`:
77231

78232
```bash
79233
ARIA_MCP_PUBLIC_URL=https://<your-tunnel>.trycloudflare.com/mcp/<ARIA_MCP_PATH_SECRET>/
80234
```
81235

82-
Verify with `curl $ARIA_MCP_PUBLIC_URL` — you should see an MCP protocol response, not 404.
236+
Verify with `curl $ARIA_MCP_PUBLIC_URL` — you should see an MCP protocol response, not a 404.
83237

84-
### 3. Flip the flag
238+
**3. Flip the flag and restart the backend.**
85239

86240
```bash
87-
INVESTIGATOR_USE_MANAGED=true
241+
echo "INVESTIGATOR_USE_MANAGED=true" >> .env
242+
make restart
88243
```
89244

90-
Restart the backend. Sentinel-triggered investigations now run on Managed Agents. Flip back to `false` and restart for a <5 min rollback to the Messages API path.
245+
Sentinel-triggered investigations now run on Managed Agents. Flip back to `false` and restart for a sub-five-minute rollback to the Messages API path — both paths share the same external contract.
246+
247+
## Behind the scenes
248+
249+
Curious how we planned and shipped ARIA in one week?
250+
[→ See our project board and roadmap](https://github.com/users/zestones/projects/28)

0 commit comments

Comments
 (0)