| # SatQuery AI — Architecture |
|
|
| > This is the index for the architecture reference. Each chapter below is a separate file in this folder. |
|
|
|
|
| This is the architecture reference for SatQuery AI. It is written as a **hub plus ten deep |
| sub-documents**, because the system is large enough that a single file would either be superficial or |
| unreadable. |
|
|
| > **Status vocabulary used everywhere in these docs:** `IMPLEMENTED` (the code exists and runs) · |
| > `VERIFIED` (checked against evidence) · `MEASURED` (a number was produced) · `ATTEMPTED` (tried, |
| > outcome recorded) · `NOT RUN` · `BLOCKED` · `DEFERRED` · `REJECTED` (tried and explicitly not |
| > accepted) · `OPEN` (known, unresolved) · `RESOLVED` · `CLOSED`. |
| > |
| > Every substantive claim in this set carries one of these tags, and every non-obvious claim cites |
| > the file it came from. |
|
|
| --- |
|
|
| ## 1. The thesis in one paragraph |
|
|
| SatQuery AI answers natural-language questions about satellite imagery. It is **not** one large |
| vision-language model. It is a **router plus specialists** system: a small learned router reads the |
| question and decides *which capability* is being asked for; the controller then runs exactly one |
| specialist; an evidence engine aggregates what that specialist produced; a confidence stage attaches |
| a calibrated (or honestly uncalibrated) number; and the whole thing is returned as one typed |
| `ResultEnvelope`. The only trained parameters in the system are six small modules sitting on frozen, |
| publicly-pinned backbones. |
|
|
| `docs/ARCHITECTURE_FREEZE.md` section 5 gives each layer exactly one verb, and the whole design |
| follows from that sentence: |
|
|
| > router **understands**; policy engine **decides**; specialists **compute**; VLM **explains**; |
| > evidence engine **proves**. |
|
|
| ## 2. Sub-documents |
|
|
| | # | Document | What it covers | |
| |---|---|---| |
| | 01 | [System overview](01-system-overview.md) | the thesis, the component inventory, the frozen-backbone strategy, what is deliberately absent | |
| | 02 | [Deployment topology](02-deployment-topology.md) | the four tiers, the gateway, the outbound tunnel, wake flow, cold start, `transport_mode` | |
| | 03 | [Request lifecycle](03-request-lifecycle.md) | the nine-state controller, validation rules, modality inference, tiling | |
| | 04 | [Router](04-router.md) | frozen MiniLM, the five-head adapter, `interpret()` vs `chooseTask()`, the lexical fallback, the label space | |
| | 05 | [Specialists](05-specialists.md) | all six tasks: entry points, preprocessing, postprocessing, outputs | |
| | 06 | [Evidence and confidence](06-evidence-and-confidence.md) | the evidence schema, the aggregation pipeline, temperature scaling, the eight execution events | |
| | 07 | [Configuration freeze](07-configuration-freeze.md) | the registry, the enforced invariants, the config hash, why it is frozen | |
| | 08 | [API contract](08-api-contract.md) | the four endpoints, the envelopes, error codes, transport headers | |
| | 09 | [Frontend](09-frontend.md) | the static pages, the Analyze console, real-vs-preview, platform traps | |
| | 10 | [Observability and operations](10-observability-and-ops.md) | health, counters, traces, what is and is not observed | |
|
|
| ## 3. The system at a glance |
|
|
| ```mermaid |
| flowchart TB |
| subgraph Client |
| U[Browser] |
| end |
| subgraph Static["Static tier"] |
| CF["Cloudflare Pages<br/>satquery.pages.dev"] |
| end |
| subgraph Gateway["Gateway tier (Render)"] |
| R["satquery-orchestrator<br/>validate · CORS · limits · timeouts · errors"] |
| end |
| subgraph Inference["Inference tier (GitHub Codespace, CPU)"] |
| A["FastAPI · build_space_app()"] |
| CTRL["Controller (9-state FSM)"] |
| ROUTER["Router<br/>MiniLM + 5-head adapter"] |
| SPEC["Specialists<br/>vqa · caption · grounding · change · change_vqa · optical_sar"] |
| EV["Evidence engine<br/>dedup · order · renumber · cap"] |
| CONF["Confidence<br/>temperature scaling"] |
| A --> CTRL --> ROUTER --> SPEC --> EV --> CONF |
| end |
| U -->|HTTPS| CF |
| CF -->|"HTTPS JSON /api/*"| R |
| R -->|"outbound long-poll POST /tunnel/agent"| A |
| CONF -->|ResultEnvelope| R |
| R -->|envelope + error translation| CF |
| ``` |
|
|
| ## 4. Cross-cutting principles |
|
|
| These recur in every sub-document and are the reason the code looks the way it does. |
|
|
| ### 4.1 One config system, no magic numbers |
|
|
| Every tunable value lives in `configs/base.yaml`. The loader (`core/config.py`) validates it against |
| the frozen architecture and hashes it. **No number is hard-coded in Python.** This is enforced |
| socially and structurally: a reviewer who finds a literal in a specialist has found a bug. |
|
|
| ### 4.2 Frozen backbones, trained modules |
|
|
| No backbone is fine-tuned. `all-MiniLM-L6-v2`, `SmolVLM-500M-Instruct`, `RemoteCLIP ViT-B/32` and |
| `CROMA-base` are all pinned **by revision** and fetched from the Hub at run time. What this project |
| trains is small: a 50,822-parameter router adapter, four heads, and one LoRA adapter. This is what |
| makes the system CPU-runnable. |
|
|
| ### 4.3 Typed contracts between every layer |
|
|
| `core/schemas.py` is the binding contract. No specialist may invent its own result shape; every |
| specialist returns a `SpecialistResult`. The schemas carry validators that encode real findings — |
| for example `Evidence` **refuses** spatial coordinates without a `coordinate_system`, because a bare |
| box is meaningless. |
|
|
| ### 4.4 Honest degradation over confident fabrication |
|
|
| The system is built so that "we could not do this" is representable and preferred to a plausible |
| guess. Concretely: |
|
|
| - a missing calibration artifact yields `method="uncalibrated"`, `calibrated=None` — **never** a |
| fabricated fitted number; |
| - a missing optional artifact **degrades** a capability rather than crashing the service; |
| - a *corrupt* artifact **raises**, because silently treating a corrupt file as "no file" would hide |
| an operational defect; |
| - the evidence engine records `dropped_over_limit` rather than silently truncating; |
| - the grounding specialist marks a result `degraded` when it produces no localisation. |
|
|
| ### 4.5 Reproducibility is a structural property |
|
|
| `EvidenceEngine.aggregate` is pure and deterministic — no clock, no RNG, no I/O. Evidence ids are |
| assigned from *sorted position*, not input order, so the same inputs produce byte-identical output. |
| `evidence_digest()` exists so that reproducibility is a test assertion rather than a hope. |
|
|
| ### 4.6 No chain-of-thought anywhere |
|
|
| `ExecutionTrace` records **observable facts only** — states, timings, counts, config hash, model |
| refs. There is no field for model reasoning and no LLM-generated confidence. This is a deliberate |
| constraint from the architecture freeze, not an omission. |
|
|
| ## 5. What the system deliberately does not have |
|
|
| | Absent | Why | |
| |---|---| |
| | Database, auth, queue | the gateway is stateless by design | |
| | GPU requirement | device is chosen via `SATQUERY_DEVICE`; all placement is `.to(device)` | |
| | Gradio GUI | the frontend is a separate static tier; `app/space_app.py` serves JSON only | |
| | End-to-end benchmark | none exists; none is claimed | |
| | Chain-of-thought | traces carry observable facts only | |
| | Backbone redistribution | backbones are fetched, pinned by revision | |
|
|
| ## 6. Where to start reading |
|
|
| - **New to the project** → [01 System overview](01-system-overview.md), then |
| [03 Request lifecycle](03-request-lifecycle.md). |
| - **Running it** → [`DEPLOYMENT.md`](../DEPLOYMENT.md) and |
| [02 Deployment topology](02-deployment-topology.md). |
| - **Auditing the numbers** → [`BENCHMARKS.md`](../BENCHMARKS.md) and [`EVALUATION.md`](../EVALUATION.md). |
| - **Understanding the router defect** → [04 Router](04-router.md) and |
| [`RESEARCH_NOTES.md`](../RESEARCH_NOTES.md). |
|
|
