Architecture

Terranoetis is a real-time geospatial intelligence platform built as a three-tier application:

• Client — React 19 + CesiumJS single-page application (Vite 7)
• Server — Node.js + Express 4 API, WebSocket realtime, JWT auth
• Persistence — SQLite (primary store) + optional Redis (cache, memory hot path). The event bus is an in-process publish/subscribe (server/pubsub.ts), not Redis.

Rendered, navigation-first version of these documents with per-capability verification data: docs site.

This document describes the system topology, request lifecycle, background services, and the runtime modules that power the platform.

---

Table of Contents

• System Topology
• Request Flow
• Background Processes
• Frontend (src/)
• Backend (server/)
• Storage Layer
• External Integrations

---

System Topology

%%{init: {'theme': 'neutral', 'flowchart': {'htmlLabels': false}}}%%
flowchart LR
    subgraph CLIENT["CLIENT (React 19 + CesiumJS)"]
        direction LR
        UI["UI\nPanels"]
        Render["Rendering\nCesium + 41 modules"]
        WS["WebSocket\nClient"]
        API["REST\nClient"]
        UI --> API
        Render --> API
        UI --> WS
    end

    subgraph SERVER["EXPRESS.JS SERVER"]
        Security["Security &\nObservability"]
        Agents["Agent &\nCognition\nSystem 1 + System 2\n9-LLM Router"]
        Engine["Analytical Engine\n150 equations\n7-stage QC\nKaggle kernels"]
        Data["Data Layer\n30+ live APIs\nFetchers + Cache"]
        Realtime["Realtime\nSentinel · Reflex\nVoice Bridge\nPubSub"]
        Services["World Model\nCausal KG · Memory\nDream · Forks\nScenarios"]
        Security --> Agents
        Security --> Data
        Agents --> Engine
        Data --> Engine
        Agents --> Realtime
        Agents --> Services
        Engine --> Services
    end

    subgraph STORAGE["PERSISTENCE"]
        SQLite["SQLite\nAuth · Scenarios\nMemory · Forks"]
        Redis["Redis\nCache · memory hot path\n(optional)"]
    end

    subgraph EXTERNAL["EXTERNAL APIs"]
        LLM["LLM Providers\nGemini · Claude\nGroq · DeepSeek"]
        Live["Live Data\nOpenSky · USGS\nTomTom · Landsat\nFIRMS · AIS · LL2"]
        Voice["Realtime Voice\nOpenAI → Gemini\n(brokered server-side)"]
    end

    CLIENT -->|HTTP| Security
    CLIENT -->|WebSocket| Realtime
    Services --> STORAGE
    Engine --> Live
    Agents --> LLM
    Realtime --> Voice

Component Inventory

---

Request Flow

The request lifecycle routes a natural-language user query through intent recognition, cognitive orchestration, and multi-stage tool execution.

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Q["User Query"] --> IR["IntentRouter\n(agent.ts)"]
    IR -->|"embedding + cosine similarity"| CO["CognitiveOrchestrator"]
    CO -->|"confidence >= 0.92"| S1["System 1\nFast real-data resolution"]
    CO -->|"0.70 <= conf < 0.92"| S2V["System 2\nVerify (10s timeout)"]
    CO -->|"conf < 0.70"| S2D["System 2\nDeep reasoning"]
    S1 -->|"real tool"| TE["Tool Execution\n(weather / earthquakes /\nflights / eonet / gdacs)"]
    S2D --> HTN["HTN Decomposition"]
    HTN --> MAD["Multi-Agent Debate\n4 agent personas"]
    MAD --> CR["Causal Reasoning"]
    CR --> CA["Counterfactual Analysis"]
    CA --> HG["Hypothesis Generation"]
    HG --> SC["Synthesis + Critic"]
    S2V --> TE
    SC --> TE
    TE -->|"API calls"| DF["Data Fetchers\n30+ sources"]
    TE -->|"Equations"| AE["Analytical Engine\n150 models"]
    TE -->|"Sandbox"| SB["Python / Node / Bash"]
    TE -->|"Foundation"| FME["Weather / Agriculture\nBayFire / SpaceX / MVT"]
    TE --> RP["Response Processing"]
    RP -->|"Cesium globe"| CG["3D Render"]
    RP -->|"Panels"| UP["UI Update"]
    RP -->|"Memory"| MS["Memory Store"]

Routing

---

Background Processes

The platform runs several continuous services that monitor live data, simulate scenarios, improve responses, and enforce safety.

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    subgraph Continuous["Continuous Background Processes"]
        SE["Sentinel Engine\nPoll watch zones\nCompare vs baseline"] --> SP["Stream Processor\nFilter, Enrich, Route"]
        SP --> AD["Anomaly Detector"]
        SP --> CE["Correlation Engine\nCross-stream fusion"]
        AD --> AL["Alerts via PubSub"]
        CE --> AL

        DE["Dream Engine\nSynthetic scenarios"] --> FK["Fork Simulation"]
        FK --> EA["Evaluate Accuracy"]
        EA --> KG["Update Causal KG"]

        SI["Self-Improver\nRecord feedback"] --> ER["Evaluate Responses"]
        ER --> DD["Detect Drift"]
        DD --> EP["Evolve Prompts"]

        REF["Reflex Engine\nMonitor channels"] --> EC["Evaluate Conditions"]
        EC --> AC["Execute Actions\nALERT / ZOOM / SCAN"]
        AC --> TR["Trauma Mode\n>=3 simultaneous"]
    end

Service Table

---

Frontend (src/)

The frontend internals are inventoried in FRONTEND.md: the 41 rendering modules (src/rendering/) with per-module purposes, the simulation overlay color map, and all 7 React hooks (useChat, useWebSocket, useKaggleSimulation, …). Routing:

---

Backend (server/)

Runtime Modules

---

Storage Layer

SQLite (better-sqlite3)

Primary store for authentication, scenarios, memory traces, forks, and application state.

Redis (ioredis)

Optional acceleration layer: caching and the sensory/working memory hot path. The server gracefully degrades to SQLite when Redis is unreachable (see server/infrastructure/redis.ts). Realtime fan-out does not depend on it — server/pubsub.ts is an in-process EventEmitter bus and WebSocket/SSE delivery runs through it.

---

External Integrations

---

Deployment

See Deployment & Operations for Docker Compose, CI/CD, environment variables, and security configuration.