# metatronsdoob369/spectral-terrain architecture

> Architecture diagram of the GitHub repository metatronsdoob369/spectral-terrain, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/metatronsdoob369/spectral-terrain
- Repository: https://github.com/metatronsdoob369/spectral-terrain

## Overview

Spectral Terrain is a temporal-geometric intelligence system for ingesting domain data, representing it in vector terrain, calibrating domain centroids, and serving nearest-neighbor, shatter, and slop queries. A typical workflow is finance snapshot collection and temporal prediction, state serialization and embedding, storage in Qdrant, calibration, then query through the HTTP server. The repository also supports Roblox physics-based prediction, source auditing, drift/integrity monitoring, and autonomous-defense tooling. The graph follows explicit excerpted calls and documented capabilities; unsampled subsystem wiring is omitted where uncertain.

Main entry points: [`scripts/ingest-finance-heatmap.ts`](https://github.com/metatronsdoob369/spectral-terrain/blob/master/scripts/ingest-finance-heatmap.ts) (Finance Heatmap Ingest), [`engine/ingest.ts`](https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/ingest.ts) (Repository Ingest), [`engine/query.ts`](https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/query.ts) (Query Engine), [`engine/query-server.ts`](https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/query-server.ts) (Query HTTP Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Acquisition & Domain"]
  node_finance_fetch["Finance Snapshot Fetch"]
  node_finance_ingest["Finance Heatmap Ingest"]
  node_finance_contract["Pool State Contract"]
  node_finance_predict["Finance t+1 Predictor"]
  node_finance_serialize["Pool State Serializer"]
  node_roblox_contract["Roblox State Contract"]
  node_roblox_predict["Roblox t+1 Predictor"]
end

subgraph group_terrain["Terrain Processing"]
  node_ingest["Repository Ingest<br/>[ingest.ts]"]
  node_calibrate["Centroid Calibration<br/>[calibrate.ts]"]
  node_embed["Embedding &amp; Geometry<br/>[embed.ts]"]
  node_terrain_contract["Terrain Contract"]
  node_qdrant[("Qdrant Vector Store")]
end

subgraph group_serving["Query &amp; Serving"]
  node_query_server["Query HTTP Server<br/>[query-server.ts]"]
  node_query["Query Engine<br/>[query.ts]"]
  node_apex["Apex Orchestrator"]
end

subgraph group_assurance["Monitoring &amp; Defense"]
  node_monitor["Drift &amp; Integrity<br/>[drift-sidecar.ts]"]
  node_integrity["Terrain Integrity"]
  node_watchdog["Watchdog Enforcement<br/>[watchdog.ts]"]
  node_threat["Threat Intake<br/>[threat-intake.ts]"]
  node_defense["Defense Writer<br/>[defense-writer.ts]"]
  node_circadian["Circadian Analysis<br/>[circadian.ts]"]
  node_canary["Canary Enforcement<br/>[canary-enforce.ts]"]
end

node_user(("Engineer / Agent"))
node_qdrant_service[("Qdrant Service")]
node_external_finance(("Finance APIs"))

node_user -->|"starts ingest"| node_finance_ingest
node_finance_ingest -->|"fetches snapshots"| node_finance_fetch
node_finance_fetch -.->|"reads market data"| node_external_finance
node_finance_ingest -->|"projects next state"| node_finance_predict
node_finance_ingest -->|"serializes state"| node_finance_serialize
node_finance_ingest -->|"uses state schema"| node_finance_contract
node_finance_ingest -->|"embeds vectors"| node_embed
node_finance_ingest -->|"writes points"| node_qdrant_service
node_user -->|"submits corpus"| node_ingest
node_ingest -->|"loads centroid"| node_calibrate
node_ingest -->|"processes source"| node_embed
node_ingest -->|"uses point types"| node_terrain_contract
node_ingest -->|"writes terrain"| node_qdrant_service
node_user -->|"provides game state"| node_roblox_predict
node_roblox_predict -->|"uses state schema"| node_roblox_contract
node_user -->|"sends query"| node_query_server
node_query_server -->|"dispatches query"| node_query
node_query -->|"embeds query"| node_embed
node_query -->|"searches vectors"| node_qdrant_service
node_query -->|"loads centroid"| node_query
node_query_server -.->|"streams events"| node_watchdog
node_user -->|"requests compression"| node_apex
node_apex -.->|"checks calibration"| node_qdrant
node_user -->|"requests drift check"| node_monitor
node_user -->|"requests validation"| node_integrity
node_user -->|"runs enforcement"| node_watchdog
node_user -->|"submits threat"| node_threat
node_user -->|"requests defense output"| node_defense
node_user -->|"runs domain analysis"| node_circadian
node_user -->|"runs canary checks"| node_canary

click node_finance_fetch "https://github.com/metatronsdoob369/spectral-terrain/blob/master/scripts/fetch-finance-snapshot.ts"
click node_finance_ingest "https://github.com/metatronsdoob369/spectral-terrain/blob/master/scripts/ingest-finance-heatmap.ts"
click node_finance_contract "https://github.com/metatronsdoob369/spectral-terrain/blob/master/contracts/finance-crypto.domain.ts"
click node_finance_predict "https://github.com/metatronsdoob369/spectral-terrain/blob/master/domains/finance-crypto-tplus1.ts"
click node_finance_serialize "https://github.com/metatronsdoob369/spectral-terrain/blob/master/domains/finance-crypto-serialize.ts"
click node_roblox_contract "https://github.com/metatronsdoob369/spectral-terrain/blob/master/contracts/roblox-luau.domain.ts"
click node_roblox_predict "https://github.com/metatronsdoob369/spectral-terrain/blob/master/domains/roblox-luau-tplus1.ts"
click node_ingest "https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/ingest.ts"
click node_calibrate "https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/calibrate.ts"
click node_embed "https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/embed.ts"
click node_terrain_contract "https://github.com/metatronsdoob369/spectral-terrain/blob/master/contracts/terrain.contract.ts"
click node_query_server "https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/query-server.ts"
click node_query "https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/query.ts"
click node_apex "https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/apex-orchestrator.ts"
click node_monitor "https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/drift-sidecar.ts"
click node_integrity "https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/terrain-integrity.ts"
click node_watchdog "https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/watchdog.ts"
click node_threat "https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/threat-intake.ts"
click node_defense "https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/defense-writer.ts"
click node_circadian "https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/circadian.ts"
click node_canary "https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/canary-enforce.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_finance_fetch,node_finance_ingest,node_finance_contract,node_finance_predict,node_finance_serialize,node_roblox_contract,node_roblox_predict toneBlue
class node_ingest,node_calibrate,node_embed,node_terrain_contract,node_qdrant,node_qdrant_service toneAmber
class node_query_server,node_query,node_apex,node_external_finance toneMint
class node_monitor,node_integrity,node_watchdog,node_threat,node_defense,node_circadian,node_canary toneRose
class node_user toneIndigo
```

## Components

### Acquisition & Domain

- [Finance Snapshot Fetch](https://github.com/metatronsdoob369/spectral-terrain/blob/master/scripts/fetch-finance-snapshot.ts): `scripts/fetch-finance-snapshot.ts`
- [Finance Heatmap Ingest](https://github.com/metatronsdoob369/spectral-terrain/blob/master/scripts/ingest-finance-heatmap.ts): `scripts/ingest-finance-heatmap.ts`
- [Pool State Contract](https://github.com/metatronsdoob369/spectral-terrain/blob/master/contracts/finance-crypto.domain.ts): `contracts/finance-crypto.domain.ts`
- [Finance t+1 Predictor](https://github.com/metatronsdoob369/spectral-terrain/blob/master/domains/finance-crypto-tplus1.ts): `domains/finance-crypto-tplus1.ts`
- [Pool State Serializer](https://github.com/metatronsdoob369/spectral-terrain/blob/master/domains/finance-crypto-serialize.ts): `domains/finance-crypto-serialize.ts`
- [Roblox State Contract](https://github.com/metatronsdoob369/spectral-terrain/blob/master/contracts/roblox-luau.domain.ts): `contracts/roblox-luau.domain.ts`
- [Roblox t+1 Predictor](https://github.com/metatronsdoob369/spectral-terrain/blob/master/domains/roblox-luau-tplus1.ts): `domains/roblox-luau-tplus1.ts`

### Terrain Processing

- [Repository Ingest](https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/ingest.ts): `engine/ingest.ts`
- [Centroid Calibration](https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/calibrate.ts): `engine/calibrate.ts`
- [Embedding & Geometry](https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/embed.ts): `engine/embed.ts`
- [Terrain Contract](https://github.com/metatronsdoob369/spectral-terrain/blob/master/contracts/terrain.contract.ts): `contracts/terrain.contract.ts`
- **Qdrant Vector Store**

### Query & Serving

- [Query HTTP Server](https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/query-server.ts): `engine/query-server.ts`
- [Query Engine](https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/query.ts): `engine/query.ts`
- [Apex Orchestrator](https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/apex-orchestrator.ts): `engine/apex-orchestrator.ts`

### Monitoring & Defense

- [Drift & Integrity](https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/drift-sidecar.ts): `engine/drift-sidecar.ts`
- [Terrain Integrity](https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/terrain-integrity.ts): `engine/terrain-integrity.ts`
- [Watchdog Enforcement](https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/watchdog.ts): `engine/watchdog.ts`
- [Threat Intake](https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/threat-intake.ts): `engine/threat-intake.ts`
- [Defense Writer](https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/defense-writer.ts): `engine/defense-writer.ts`
- [Circadian Analysis](https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/circadian.ts): `engine/circadian.ts`
- [Canary Enforcement](https://github.com/metatronsdoob369/spectral-terrain/blob/master/engine/canary-enforce.ts): `engine/canary-enforce.ts`

### Other components

- **Engineer / Agent**
- **Qdrant Service**
- **Finance APIs**

## Connections

- Engineer / Agent → Finance Heatmap Ingest: starts ingest
- Finance Heatmap Ingest → Finance Snapshot Fetch: fetches snapshots
- Finance Snapshot Fetch → Finance APIs: reads market data
- Finance Heatmap Ingest → Finance t+1 Predictor: projects next state
- Finance Heatmap Ingest → Pool State Serializer: serializes state
- Finance Heatmap Ingest → Pool State Contract: uses state schema
- Finance Heatmap Ingest → Embedding & Geometry: embeds vectors
- Finance Heatmap Ingest → Qdrant Service: writes points
- Engineer / Agent → Repository Ingest: submits corpus
- Repository Ingest → Centroid Calibration: loads centroid
- Repository Ingest → Embedding & Geometry: processes source
- Repository Ingest → Terrain Contract: uses point types
- Repository Ingest → Qdrant Service: writes terrain
- Engineer / Agent → Roblox t+1 Predictor: provides game state
- Roblox t+1 Predictor → Roblox State Contract: uses state schema
- Engineer / Agent → Query HTTP Server: sends query
- Query HTTP Server → Query Engine: dispatches query
- Query Engine → Embedding & Geometry: embeds query
- Query Engine → Qdrant Service: searches vectors
- Query Engine → Query Engine: loads centroid
- Query HTTP Server → Watchdog Enforcement: streams events
- Engineer / Agent → Apex Orchestrator: requests compression
- Apex Orchestrator → Qdrant Vector Store: checks calibration
- Engineer / Agent → Drift & Integrity: requests drift check
- Engineer / Agent → Terrain Integrity: requests validation
- Engineer / Agent → Watchdog Enforcement: runs enforcement
- Engineer / Agent → Threat Intake: submits threat
- Engineer / Agent → Defense Writer: requests defense output
- Engineer / Agent → Circadian Analysis: runs domain analysis
- Engineer / Agent → Canary Enforcement: runs canary checks