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.

```mermaid
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.