docs/ARCHITECTURE.md

Sofia Engine Runtime Architecture

Sofia Engine is structured as a unidirectional, 10-layer deterministic pipeline designed for scientific telemetry processing, machine condition monitoring, and bounded edge intelligence.

---

1. Unidirectional Data Flow

The runtime enforces strict layer boundaries. Dependencies only point downwards; higher-level diagnostics or advisory copilots never feed uncontrolled state back into deterministic signal processing.

flowchart LR
    S["Physical Sensors"] --> I["Telemetry Ingestion"]
    I --> Q["Validation & Signal Quality"]
    Q --> B["Bounded Buffers"]
    B --> D["Scientific DSP"]
    D --> F["Versioned Feature Vector"]
    F --> M["Inference Backends"]
    M --> E["Evidence Fusion"]
    E --> H["Diagnostics & Health"]
    H --> P["Policy Engine"]
    P --> O["Advisory / Controlled Output"]

---

2. Layer Definitions

Layer	Component	Responsibility	Contracts & Invariants
0	Physical Sensors	Piezoelectric accelerometers, voltage/current transducers, RTDs, pressure sensors	Raw electrical quantities ($V, mA, mV/g$)
1	Telemetry Ingestion	Packaging time-series samples into bounded frames	SignalMetadata, SignalFrame ($\le 65536$ capacity ceiling)
2	Validation & Quality	Quality flagging (GOOD, DEGRADED, UNCERTAIN, INVALID, SATURATED)	IEEE 754 non-finite check; timestamp plausibility
3	Bounded Buffers	Deterministic circular ring buffers	Static allocation; zero dynamic growth post-init
4	Scientific DSP	FFT, Welch PSD, Hilbert analytic envelope, Fortescue symmetrical components	Parseval energy conservation; frequency axis from $f_s$, not wall-clock
5	Feature Extraction	Statistical, spectral, and domain feature extraction	FeatureVector (Schema v3.0, ordered fixed tuple, unit-bearing)
6	Inference Backends	Anomaly detectors, linear models, Assembly Neural Network	ModelBackend interface, manifest checksum enforcement
7	Evidence Fusion	Combining detection signals into versioned evidence bundles	EvidenceBundle, Noisy-OR confidence aggregation
8	Diagnostics & Health	Machine health evaluation, uncertainty interval calculation	HealthScore ($0-100 \pm \Delta$), DiagnosticEngine
9	Safety & Policy	Command authorization, replay protection, interlock gating	Default DENY posture, Nonce + TTL replay guard
10	Advisory Output	Diagnostic reports, telemetry export, advisory LLM copilot	LLMs are strictly advisory; isolated from machine actuation

---

3. Cross-Language Conformance

Sofia Engine maintains verified mathematical consistency across three target implementations:

1. Python (sofia_ai): Reference scientific implementation for gateways, edge servers, and cloud pipelines (NumPy-based, zero heavy framework dependencies).
2. TypeScript (@rootcastle/sofia-engine): Edge gateway, industrial browser, and Node.js runtimes with identical statistical contracts.
3. C99 Embedded (embedded/): Microcontroller target (ARM Cortex-M, RISC-V) featuring zero heap allocation post-init (malloc prohibited) and Q16.16 fixed-point arithmetic.