# Architecture Overview
## The problem
The traditional Windows-gaming-on-Linux stack is:
```text
Windows game → Wine → Proton integration → vkd3d-proton/DXVK → Vulkan → kernel/GPU driver
```
It works, and it contains decades of hard-won compatibility knowledge. But
it also contains **boundaries**: Windows→Unix transitions, server calls,
path translations, per-call FFI, redundant allocations, duplicated state
tracking, and synchronization layers that each add cost and latency.
Katra3D does not propose replacing the stack. It proposes replacing the
**expensive boundaries**, guided by measurement.
## The target architecture
```text
Windows game
│
▼
Katra3D runtime
│
┌────────────────┴─────────────────┐
│ │
explicit intent inferred intent
│ │
DirectStorage KatraFlow
│ │
└────────────────┬─────────────────┘
▼
Semantic request graph
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
I/O Memory Shader
│ │ │
└────────────────────┼────────────────────┘
▼
Unified scheduler
│
▼
Native D3D12 hot paths
│
┌───────────┴────────────┐
▼ ▼
Katra native C fallback
│
▼
Vulkan
│
▼
GPU
```
**The semantic request graph is the architectural center** — not Wine, not
vkd3d, not Vulkan, not io_uring. Those are execution mechanisms.
## Principles
1. **Preserve behavior, not implementation history.** Every upstream
workaround is reduced to the observable behavior it preserves, tested,
and re-implemented cleanly — or kept verbatim as a fallback.
2. **Performance must be earned.** Every native replacement passes
`OBSERVE → SHADOW → NATIVE_EXPERIMENTAL → NATIVE_DEFAULT` with evidence
at every gate (`docs/standards/promotion-gates.md`).
3. **Cold code can remain C indefinitely.** Profiling decides.
4. **Hot boundaries matter more than large modules.** A 300-line boundary
crossed 3M×/s beats a 200k-line subsystem run once.
5. **Fallback is a first-class feature**, at coarse module boundaries, with
no fine-grained FFI chatter.
6. **The C↔Rust interface is boring** (§22): opaque handles + semantic
operations (`docs/ffi-policy.md`). Inside Rust, subsystems cooperate
directly.
7. **No benchmark theater** (§40): no cherry-picking, no fabricated values,
complete `not_measured` lists.
## The crates
| `katra-core` | vocabulary: error model, event kinds, payloads, IDs, policy types |
| `katra-graph` | the semantic request graph + CPM analysis |
| `katra-prof` | the profiler: zero-alloc hot path, per-thread buffers |
| `katra-trace` | the versioned trace format + verification |
| `katra-report` | Pareto, causality, critical paths, receipts |
| `katra-replay` | deterministic replay, verify, compare |
| `katra-flow` | universal storage optimization (observe/shadow/prefetch) |
| `katra-io` | capability-abstracted async I/O (io_uring + sync pool) |
| `katra-memory` | lifetime-aware staging arenas |
| `katra-sync` | fences, events, epochs, cross-domain joins |
| `katra-schedule` | deadline-aware unified scheduling |
| `katra-dstorage` | DirectStorage frontend (converges with KatraFlow) |
| `katra-shader` / `katra-cache` | layered shader/PSO cache |
| `katra-d3d12` | evidence-gated hot-path dispatch (fallback today) |
| `katra-vulkan` | capability model + submission/residency policy |
| `katra-abi` | `libkatra3d` — the C ABI |
| `katra-courts` | the falsifiable evidence harness |
## Cross-cutting concerns
- **Observability**: everything flows through the trace format
(`docs/architecture/observability.md`).
- **Determinism**: seeded workloads, monotonic sequences, stable
fingerprints — replays are comparable.
- **Budgets**: documented in `docs/architecture/performance-budget.md` and
enforced by courts.
- **Power**: performance-per-watt is a first-class metric
(`docs/performance/power.md`).
- **Privacy**: profiles are local; file *identity hashes*, not contents
(§43).