# Architecture

### *biological in inspiration. rigorous in implementation.*

---

## the synaptic gap

The design philosophy starts with a metaphor and refuses to let it become decorative. A synapse is the cleft between two neurons — the gap where electrical signal becomes meaning, where pre-synaptic firing crosses through chemistry into post-synaptic decision.

Syn_OS treats the operating system itself as the synaptic cleft.

```
Hardware                    →  pre-synaptic firing
Syn_OS (the OS itself)      →  the synapse
Application + intent        →  post-synaptic decision
```

This is not branding. It's the framing every architectural decision is checked against. *Where in the gap does this live? What does it translate from, and what does it translate into?*

---

## the four pillars

The system rests on four load-bearing components, each genuinely irreplaceable in the design.

### the kernel

A custom Linux 6.19 build with significant Rust integration — not Linux-with-Rust-bolted-on, but Linux taking the rust-in-kernel work seriously. Memory-safe modules where memory safety matters most. The kernel is not a black box — it's an active participant in the system's awareness of itself.

The numbers say it plainly:

| | |
|---|---|
| **Rust kernel modules** | **22**, loadable |
| **Rust LOC at ring 0** | **29,269** |
| **hand-written C** | **492 lines** — nine thin FFI shims, nothing more |
| **the rest of the C** | kbuild-generated artifacts, not authored |

The AI and security surface is *entirely Rust*. The only C anyone writes is the last-mile glue to legacy kernel-source helpers that have no Rust binding yet — and as Rust-for-Linux upstream grows, that shrinks. Modules expose their capability through a misc **character-device + `ioctl`** interface (`/dev/synos_*`): root-only, `CAP_SYS_ADMIN`-gated, Ed25519-signed — the kernel refuses to load a module that isn't signed. Every one is QEMU-boot-validated: the build boots the kernel and asserts each `ioctl` op responds before the module ships.

The deeper internals — what those modules *decide* — live with the source. The shape is public; the special sauce stays in the pot.

### ALFRED

The operator's companion. A local AI daemon that runs on the box, not in the cloud. Modeled loosely after the structure of a biological brain: many small specialized regions, each with a job, coordinating through a central conductor. ALFRED watches the system, anticipates the operator's loop, surfaces context when context is what's missing. It does not phone home.

### GRIMOIRE

The gamified cybersecurity training surface — the public face of the platform, covered in detail in [its own document](./GRIMOIRE.md). GRIMOIRE turns cybersecurity practice into a world worth living inside. Factions, labs, boss contracts, economy, narrative. The training arc that takes a novice to an operator and means it.

### the mesh

When the system is ready to extend, it does so as a mesh — encrypted, peer-to-peer, sovereign. Multiple machines, owned by you, talking to each other on terms you set. The mesh is where the platform stops being a single laptop and becomes infrastructure.

---

## the three-image strategy

Syn_OS is built once and ships in tiers. The split exists because the audiences are genuinely different.

| Image | Audience | Posture |
|---|---|---|
| **Operator** | The team that builds Syn_OS. Internal. | The full surface. Not distributed publicly. |
| **GRIMOIRE Public** | Students, cohorts, self-taught practitioners. | The training platform — same world, gated tooling. |
| **Goodlife** | AI researchers, post-quantum experimenters, civilian work. | Research-oriented defaults. AI tooling. Civilian-safe. |

The boundaries are enforced. What ships in each image is what was meant to ship. The mechanism is mechanical, not honor-system.

---

## the substrate

Below the four pillars, there's a substrate of practical engineering work that makes the higher-level vision viable. None of this is glamorous. All of it is required:

- **Rust everywhere it makes sense.** The bulk of the system is memory-safe code.
- **A self-healing build pipeline.** Producing the images is a multi-stage process that recovers from individual failures without losing the whole run.
- **Post-quantum cryptography in the toolkit.** Built for the cryptographic transition that's already underway.
- **Reproducible builds and signed releases.** Verifiable provenance from build to delivery.
- **Documentation that takes itself seriously.** Living documents, version-aware, checked against the codebase.

---

## design axioms

Three axioms, applied recursively:

1. **The synaptic gap is real.** Hardware is not the OS. The OS is not the application. The OS is the gap, and the quality of the system is the quality of that translation.
2. **Memory safety where it matters.** Where Rust earns its keep, Rust earns its keep.
3. **Tiers are mechanical.** Capability boundaries between images are enforced by the build, not by goodwill.

---

## further reading

The deeper architectural surface — kernel internals, AI daemon mechanics, mesh authentication, build pipeline — lives with the source. The shape described here is the public-facing pillars.

The shape is enough to know whether the rest will interest you.
