# Architecture Overview

Orxaq is structured as five concentric rings. Each ring depends only on rings with lower numbers. This enforces a strict dependency hierarchy: the kernel never imports from credit risk, credit risk never imports from the CLI, and so on.

```mermaid
graph TB
    R5[Ring 5: Experiences] --> R4[Ring 4: Orchestration]
    R5 --> R3[Ring 3: Intelligence]
    R4 --> R3
    R3 --> R2[Ring 2: Data Fabric]
    R3 --> R1[Ring 1: Kernel]
    R2 --> R1
```

## Design Principles

**Stdlib-only kernel (ADR-007).** Ring 1 has zero external dependencies. This means the core type system, audit log, and DAG operations can never break due to a third-party upgrade.

**Causal over correlational (ADR-009).** Every model in Orxaq operates on causal graphs, not feature matrices. PD models are fitted along causal paths. Stress tests propagate interventions through the DAG. Fair lending decomposes effects into direct and indirect causal channels.

**Compliance-first (ADR-008).** SR 11-7 is the control superset. Every module logs to the hash-chained audit trail. Every significant decision is recorded as an ADR before implementation.

**Fail-closed quality gates (ADR-016).** Data enters the system through quality gates that check completeness, bounds, types, and freshness. Data that fails any gate is rejected, not patched.

## Module Map (Miller's Law — max 7 per directory)

```
src/orxaq/                       (7 modules)
  kernel/                        Ring 0 — types, DAG, audit, crypto, plugins
  intelligence/                  Ring 1 — causal discovery algorithms
  fabric/                        Ring 2 — data connectors, quality, validation
    validation/                  Validation pipeline (moved from top-level)
  orchestration/                 Ring 3 — providers, routing, integration facade
    providers/                   LLM provider abstraction
    integration.py               OrxaqEngine facade (moved from top-level)
  experiences/                   Ring 4 — CLI, dashboard, editor, skins
    cli.py                       CLI entry point (moved from top-level)
    dag_editor/                  Interactive DAG editor
    skins/                       Visual theme skins
    static/                      Frontend assets
  credit/                        Domain — causal PD, CECL, CCAR, fair lending
  enterprise/                    Enterprise — health checks, config

tests/                           (mirrors src/ structure)
  benchmarks/                    Performance benchmarks (moved from top-level)

deploy/                          Deployment artifacts
  Dockerfile                     Container image (moved from top-level)
  helm/                          Kubernetes charts
```

See [Five Rings](five-rings.md) for detailed descriptions of each ring.
