Platform architecture
Full description: Read the full narrative
Terranoetis is a three-tier application: a React 19 + CesiumJS single-page client (Vite 7), a Node.js + Express 4 API (TypeScript run via tsx), and SQLite (primary store) with Redis as an optional cache/memory hot path. The client talks REST + SSE + WebSocket to the API; the API orchestrates live-data fetchers, the 150-equation analytical engine, the hazard-simulation runners and the cognitive pipeline.
Server assembly
| Order | Component | Detail | Source |
|---|---|---|---|
| 1 | helmet CSP + Permissions-Policy | explicit CSP incl. Cesium/WS allowances; HSTS 1 yr in prod | server/index.ts:233-272 |
| 2 | cors | static allowlist origin = CLIENT_ORIGIN, credentials on | server/index.ts:273 |
| 3 | body limits 5 mb, x-powered-by off | server/index.ts:274-276 | |
| 4 | pino request logger → prom-client metrics | before auth so all traffic is metered | server/index.ts:279-280 |
| 5 | auth endpoints pre-guard | login rate-limited 5/15 min; refresh; dev-login non-prod only | server/index.ts:306-314 |
| 6 | global /api guard | public allow-list: health/metrics/config/OpenAPI + rate-limited read-only data routes (300/min/IP) + unthrottled public non-data routes (tiles, pulse, share-token reads); everything else requires JWT | server/index.ts:373-487 |
| 7 | routers | foundation-models, fork, pulse, /api/kaggle, analytical-models, openapi | server/index.ts:489-494 |
| 8 | DynamicToolRegistry (DB-persisted; 210 tools loaded at boot) + Omninet init + local GGUF spawn | llama-server :11436 when model file present | server/index.ts:513-817 |
| 9 | listen() background engines | sentinel, monitors, forecast ledger, reflex, forks, entropy, discovery, dream, memory system, power saver | server/index.ts:14448-14488 |
| 10 | graceful shutdown | stop engines → close HTTP → queue shutdown 10 s → close DB | server/index.ts:14519-14573 |
Request flow (chat)
POST /api/agent/ask(authGuard, 30/min, zod-validated ≤ 10k chars + ≤ 4 images) — server/index.ts:9749,9167 server/middleware/validate.ts:3-41- Intent classification: deterministic keyword router; embedding path if conf < 0.85; LLM deep-path only if conf < 0.7 — server/agent.ts:389-800 server/index.ts:9835-9851
- Cognitive orchestration: System 1 fast path (similarity ≥ 0.92), S1 + 10 s S2 verification (0.70–0.92), full System 2 with 45 s hard cap (< 0.70) — server/cognition/cognitiveOrchestrator.ts:251-295,386-388
- Tool execution: live-data fetchers, analytical tools, sandbox, simulation jobs; ≤ 3 tool rounds; SSE streamed with 15 s heartbeats and a hard 150 s run cap — server/index.ts:9801-9811,10966-10983
- Write-through to the chat knowledge graph and reasoning traces — server/index.ts:11237 server/kgV2/chatKgBridge.ts:28
Module inventory
LOC per directory and each module’s purpose are tabulated in the prose document (BACKEND.md), verified against the tree. Highlights of interest to researchers: analytical-models/ (23,866 LOC), kaggle/ (3,105), cognition/ (2,760), sentinel/ (3,191), memoryV2/ (2,091).
Persistence and realtime plumbing
| Subsystem | Implementation | Source |
|---|---|---|
| Primary store | SQLite server/realtime.db, WAL + busy_timeout 5000, FKs on; 47 schema tables + runtime tables (provider_stats, system1_cache, job_queue…) | server/db/index.ts:6-18 server/db/schema.sql:47 tables (counted) |
| Cache/hot path | Redis via ioredis when reachable; graceful SQLite fallback | server/infrastructure/redis.ts:degradation |
| Event bus | In-process EventEmitter pub/sub (server/pubsub.ts) — not Redis pub/sub; WebSocket fan-out runs through this bus | server/pubsub.ts:1-21 |
| Realtime transports | WebSocket only on /ws/agent + /ws/voice; SSE for chat and job status | server/websocket.ts:74-80 server/kaggle/routes.ts:225 |
| Job queue | SQLite-backed SimpleQueue, 10 concurrent, max 3 attempts, recurring timers (MVC refresh 60 s, plugin scan 30 s…) | server/queue/simple-queue.ts:22-60 server/index.ts:1006-1039 |