A visible, editable interface for the AEOLUS ventilation simulation: define a habitat topology now, then connect it to local fault inference and bounded virtual recovery.
AEOLUS is a simulation-first Physical AI prototype for the Arm Create AI Optimization Challenge 2026. This repository contains the standalone web interface. Its first live layer is Connections, a graph workspace where the team can define rooms, processing areas, and directed airflow actuators before the topology is consumed by the Python simulation.
The interface makes the future control loop tangible:
simulated plant -> telemetry -> local fault inference -> safety governor -> bounded virtual actuation
^ |
+---------------- changed plant state and replay -------------------+
The current website is deliberately honest about its boundary: it edits a versioned simulation topology. It does not control real spacecraft, life-support, HVAC, or production equipment.
Physical AI systems are easier to trust when their environment, signals, decisions, and recovery actions can be inspected together. AEOLUS starts with the system map itself. A room is not just a label, and an actuator is not just a line on a diagram: both carry configurable domain bias that the later plant model and safety logic can consume.
The web experience gives the team a shared visual language for the proof loop before model inference and Arm benchmark evidence are added.
- Connections workspace - four-room starter topology with crew cabins, a lab, and an air-processing bay.
- Directed actuators - add one-way airflow paths or paired return paths with independent state.
- Editable domain bias - configure occupants, generation, capacity, effectiveness, commandability, notes, and tags.
- Draft workflow - save named drafts locally, import/export versioned JSON, reset changes, and delete drafts with confirmation.
- Optional shared drafts - synchronise through a private Vercel Blob store when deployment storage is connected.
- Whitelist editor access - the site can stay public while GitHub or Google OAuth limits synchronise and delete actions to approved email addresses.
- Responsive interface - usable on desktop, 4K displays, tablets, and mobile widths with labelled controls.
- Clear roadmap states - Live system, Scenarios, Telemetry, and Benchmarks are visible as planned layers rather than presented as finished functionality.
flowchart LR
Browser["Browser"] --> Shell["Astro page shell"]
Shell --> Workspace["React Connections workspace"]
Workspace --> Local["localStorage draft fallback"]
Workspace --> API["/api/topology"]
API --> Blob["Private shared draft storage"]
Workspace -. "versioned JSON" .-> Simulator["Future Python plant loader"]
The graph document is intentionally independent of React Flow internals. That keeps visual layout concerns such as node position separate from the serializable topology that the simulator will eventually load.
Every topology is stored as a versioned document. A simplified example:
{
"version": 1,
"name": "Habitat circulation / draft 01",
"nodes": [
{
"id": "cabin-a",
"label": "Crew Cabin A",
"preset": "crew_cabin",
"position": { "x": 80, "y": 100 },
"bias": { "occupants": 1, "co2_generation": 1.0 }
}
],
"connections": [
{
"id": "cabin-a-to-processing-bay",
"source": "cabin-a",
"target": "processing-bay",
"preset": "fan",
"bias": { "capacity": 10.0, "effectiveness": 1.0, "commandable": true }
}
]
}Stable IDs, editable labels, directional connections, configurable bias, and a schema version are the important boundaries. The visual editor can evolve without forcing the Python simulator to understand React Flow objects.
| Layer | Choice | Purpose |
|---|---|---|
| Page shell | Astro | Fast deployable pages and server endpoint support |
| Interactive UI | React | Stateful topology editing island |
| Graph canvas | React Flow | Nodes, directed edges, selection, handles, and minimap |
| Validation | Zod | Versioned graph document boundary |
| Icons and type | Lucide, Space Grotesk, IBM Plex Mono | Compact controls and technical interface hierarchy |
| Shared storage | Vercel Blob | Optional private draft persistence |
aeolus-web/
├── public/ # Public project brief and static assets
├── src/
│ ├── components/ # React islands and interface styles
│ ├── layouts/ # Astro page shell
│ ├── lib/ # Graph contract and navigation data
│ ├── pages/ # Routes and /api/topology
│ └── styles/ # Global theme tokens and typography
├── .env.example # Safe environment variable names only
├── .env.local.example # Local OAuth setup template, no real secrets
├── astro.config.mjs # Astro and Vercel adapter configuration
├── package.json
└── README.md
Generated directories such as node_modules, .astro, dist, and .vercel are intentionally ignored.
Use the repository root as the working directory:
npm install
npm run check
npm run dev -- --host 127.0.0.1 --port 4321Open http://127.0.0.1:4321. The website works without a backend. Drafts use browser storage, JSON import/export remains available, and the shared API reports that Blob storage is not configured until credentials are added.
The sign-in chooser requires AUTH_SECRET. A real GitHub or Google sign-in also requires OAuth app credentials. Copy .env.local.example to .env.local, fill in the credentials, and register both callback URLs with the providers. Keep .env.local private.
Before sharing a change, run the production checks:
npm run check
npm run build
npm run previewTo stop the Astro development server, run this separately:
npx astro dev stopThe website is designed for public viewing. Reading the topology does not require an account. Shared mutations are protected separately:
GET /api/topologyremains public so visitors can see the current draft list and load a topology.POST /api/topologyandDELETE /api/topologyrequire an authenticated GitHub or Google session.- The authenticated account email must appear in
AUTH_ALLOWED_EMAILS. - The browser disables editing controls for public visitors, but the API is the real security boundary.
Configure these variables in the deployment environment:
AUTH_SECRET=
AUTH_GITHUB_ID=
AUTH_GITHUB_SECRET=
AUTH_GOOGLE_ID=
AUTH_GOOGLE_SECRET=
AUTH_ALLOWED_EMAILS=editor.one@gmail.com,editor.two@gmail.com
Use AUTH_URL=https://icarus-theta-five.vercel.app in Vercel. For local development, use AUTH_URL=http://127.0.0.1:4321.
Create GitHub and Google OAuth apps with these callback URLs:
https://your-domain.example/api/auth/callback/github
https://your-domain.example/api/auth/callback/google
For the current Vercel domain, use the stable project domain rather than a deployment-specific preview URL. Keep AUTH_SECRET, both OAuth client secrets, and the Blob credentials private. AUTH_ALLOWED_EMAILS is a comma-separated list of exact email addresses. The sign-in page intentionally exposes only GitHub and Google.
AEOLUS is a research simulation for a hackathon. The values in the current model are abstract units, not spacecraft measurements or operational safety thresholds. Authentication limits shared draft writes, but the project still needs audit logging, stronger team administration, and optimistic concurrency before it should be used beyond a controlled demonstration.
- Connect the graph document to a generalized Python plant model.
- Add live telemetry and the primary-fan degradation scenario.
- Add local fault inference with reproducible FP32 and INT8 benchmark evidence on Arm.
- Add a deterministic safety governor, bounded redundant-fan actuation, and the
HAND_BACKpath. - Add recovery traces that prove a virtual command changes the simulated plant state.
Built by Alex, Ben, and MS-Mesh for the Arm Create 2026 Physical AI track.