# ODGS Technical Architecture v2.0
## The Sovereign Sidecar Model

### 1. Core Philosophy: Configuration as Law
The Open Data Governance Standard (ODGS) strictly separates **Policy Definition** (Legislative/Judiciary) from **Policy Enforcement** (Executive). The Executive plane (the code) has *zero* hardcoded logic; it blindly executes the rules defined in the JSON configuration files.

### 2. The 5-Plane Architecture

| Plane | Component | Role | Artifacts |
| :--- | :--- | :--- | :--- |
| **Legislative** | The Ontology | Defines *Meaning* | `ontology_graph.json`, `standard_metrics.json` |
| **Judiciary** | The Rules | Defines *Constraints* | `standard_data_rules.json`, `root_causes.json` |
| **Executive** | The Interceptor | Enforces *Compliance*| `interceptor.py`, `physical_data_map.json` |
| **System** | The Interface | Manage *Interaction* | `api.py`, `platform_ui` |
| **Audit** | The Record | Proves *Reality* | `sovereign_audit.log` (Git-backed) |

### 3. The Interceptor (Executive Plane)
The `OdgsInterceptor` is the core enforcement mechanism. It sits as a sidecar to any data process.

#### 3.1 Dynamic Rule Engine
-   **No Hardcoded Logic:** All validation logic is stored in `standard_data_rules.json` as `logic_expression`.
-   **Safe Execution:** The `simpleeval` library is used to parse and execute these expressions safely (no `eval()`).
-   **Context:** Rules have access to the data payload and helper functions (`regex_match`, `parse_date`, `today`).

#### 3.2 Tri-Partite Binding (Article 12)
To meet EU AI Act Article 12 (Record-Keeping), every audit log entry cryptographically binds three elements:
1.  **The Event:** `SHA-256(Input Data Payload)`
2.  **The Law:** `SHA-256(Project State / Governance Definitions)`
3.  **The Configuration:** `SHA-256(System Configuration)`

This ensures that a log entry proves not just *what* happened, but *why* it was allowed/blocked at that exact moment in time.

### 4. Zero-Trust Persistence (Data Sovereignty)
The ODGS Reference Implementation uses a **"Git-as-Backend"** pattern for audit logs to ensure sovereignty and immutability without external dependencies.

-   **Adapter:** `src/odgs/system/adapters/git_log_adapter.py`
-   **Mechanism:**
    1.  Log entry is written to `src/odgs/audit_logs/YYYY-MM-DD.jsonl`.
    2.  Adapter immediately triggers `git add` and `git commit` for that file.
    3.  The Git hash of the commit is returned as the "Receipt".
-   **Benefit:** The audit trail is cryptographically chained, distributed, and owned entirely by the deployer (user).

### 5. API Surface
The system exposes a lightweight FastAPI interface (`src/odgs/system/api.py`).

| Endpoint | Method | Purpose |
| :--- | :--- | :--- |
| `/api/sovereign/intercept` | POST | Main enforcement point. Accepts process URN and data context. Returns GRANTED/BLOCKED. |
| `/api/sovereign/logs` | GET | Verification endpoint to view the immutable audit trail. |
| `/api/sovereign/hash` | GET | Returns the current master hash of the governance definition (The "Passport"). |
