Active Development·Developer Tools · Distributed Systems·2026
Aether
Point it at a repository and it streams back an evidence-backed model of the stack — every claim carrying a confidence score and the file paths that justify it.
Submit a repository → detector events arrive over Server-Sent Events → the manifest lands. Recorded from the running stack.
A completed ingestion, end to end. The timeline settles at Complete after nine events, then the manifest resolves all eight fields — each carrying a value, a rubric-derived confidence, and the evidence paths that justify it.
Caught mid-stream. A gap-free per-stream sequence lets a client replay from Last-Event-ID and live-tail with no missed or duplicated events.
Nothing about ingestion is specific to the bundled target — the same detectors run against fastapi/full-stack-fastapi-template, shallow-cloned over the network. Step 4 reports not detected: with no evidence for service ports, the pipeline declines to guess.
Overview
Aether turns 'point it at a repo' into a persisted, evidence-backed ProjectManifest, streamed to the browser in real time. It is built skeleton-first: this release wires every architectural joint — durable job queue, transactional event outbox, migrations, live streaming, deterministic ingestion, enforced module boundaries — and proves them end to end before any AI is layered on. It is the foundation for citation-first automated bug investigation.
Problem
Tools that reason about code are only as trustworthy as the plumbing beneath them. Most start with the impressive analysis and bolt on infrastructure later, which is exactly backwards: if the queue drops jobs, the event stream skips, or a claim cannot be traced to a file, no amount of model quality rescues the output. The hard, unglamorous parts — exactly-sequenced streaming, crash recovery, provenance — have to be load-bearing first.
Solution
A monorepo where a worker clones or copies a repository into a throwaway workspace, eight deterministic detectors identify its stack, and each detection is persisted with a confidence score and the file paths backing it. Progress streams to a React SPA over Server-Sent Events. To keep ingestion honest, the project ships its own target — ShopFault, a small commerce app carrying a genuine duplicate-order race that reproduces statistically — treated as a foreign repository the rest of the codebase is mechanically forbidden to import.
Architecture
Four services under one Docker Compose command: PostgreSQL, a FastAPI API, a worker, and an nginx-served React SPA. The queue is Postgres itself — FOR UPDATE SKIP LOCKED claiming, heartbeats, a stale-job reaper, exponential-backoff retries, and crash recovery — with no external broker. State changes and their events commit in a single transaction through an outbox table, so the SSE endpoint can replay a gap-free sequence and then live-tail. The SPA's API client is generated from the API's own OpenAPI schema rather than hand-written, and import-linter enforces the layering (schemas → db → api/worker, and never api ↔ worker) in CI.
Tech stack
Python
FastAPI
SQLAlchemy
Alembic
Pydantic
PostgreSQL
React
TypeScript
Vite
TanStack Query
Tailwind CSS
pytest
Playwright
mypy
Docker
GitHub Actions
Engineering decisions
PostgreSQL as the job queue instead of Redis or a broker — one fewer moving part, and job state stays transactional with the domain data it describes.
A transactional event outbox: the state change and the event that announces it commit together, so a crash can never leave the stream disagreeing with the database.
Server-Sent Events over WebSockets — the traffic is one-directional, and SSE gives replay-from-Last-Event-ID for free.
Zero LLM calls in this phase. Detection is deterministic and therefore assertable field-by-field in an acceptance test.
Environment files are inventoried by key name, never value, with a redaction filter on every event and log payload — a planted-marker test asserts nothing leaks.
The target application lives in the repo but is treated as foreign: a standing isolation check fails the build if any application code imports it.
Challenges
Guaranteeing a gap-free event sequence under concurrent writers required a dedicated per-stream counter allocated inside the same transaction as the event insert — an ordinary auto-increment column leaves visible holes when transactions interleave.
At-least-once delivery means handlers must be idempotent; re-ingesting the same commit had to resolve to the same project version rather than quietly duplicating rows.
Proving the queue's recovery paths meant testing against a real PostgreSQL rather than mocks — crash, stale-lock reaping, and retry semantics only exist at the database level.
Performance
Local-path ingestion completes in roughly a second; a shallow clone of a public GitHub repository adds only the network time.
Acceptance gate asserts on API and database facts rather than log text, and requires the target's duplicate-order bug to reproduce in at least 3 of 10 concurrent trials.
191 backend tests plus 22 target tests run against a real PostgreSQL in CI, alongside type-checking, import-boundary contracts, and Playwright end-to-end specs.
Lessons learned
Building the skeleton first is slower for a month and faster forever — every later feature lands on joints that are already proven.
A queue is a set of failure modes, not a data structure. Heartbeats, reapers, and idempotency are the actual product.
Confidence scores are only worth showing if the evidence behind them is one click away; otherwise they are decoration.
Shipping a deliberately buggy target alongside the tool made the acceptance criteria concrete instead of aspirational.
Future improvements
A static 'twin': Python AST and tree-sitter extraction into a persisted code graph, with cross-layer URL matching.
Dynamic observation through a sandboxed runner and scripted browser sessions that capture evidence.
Evidence-driven, citation-first bug investigation layered on top of the manifest and graph.
Test generation and sandboxed patch validation producing verified fix reports.
Engineering notes
What's shaping this build.
Design goals, philosophy, planned architecture, and where the project stands today. No fabricated benchmarks — only what's actually driving decisions.
ExpandCollapse
Design goals
Every claim the system makes must be traceable to a file path.
No architectural joint left as a stub — the queue, outbox, and stream are real or the phase is not done.
Module boundaries enforced by a tool in CI, not by convention.
An honest target with a real bug, so acceptance criteria cannot be gamed.
Philosophy
Build the spine before the brain. Deterministic, verifiable plumbing first; the model comes later and inherits a substrate it can be trusted on.
Planned architecture
The manifest becomes the base layer for a persisted code graph, which in turn grounds citation-first investigation — each phase adding capability without loosening the evidence guarantee.
Current stage
Phase 1 is complete, tagged v1.0.0-phase1 and licensed MIT: queue, outbox, SSE with replay and reconnect, deterministic ingestion, the live frontend, the ShopFault target, CI, and an end-to-end acceptance gate. Static analysis and the investigation layer are next.
