Architecture — SOFIA

Date: 17/04/2026 Author: Aurele — Method architect Status: Reference

1. Identity

Motivation

Three interdependent concepts are at the origin of SOFIA:

• Persona — an LLM constrained by a role, a scope, and prohibitions
• Friction — the disagreements that emerge from constraints between personas
• Artifact — the structured file that materializes exchange and trace

The orchestrator (human) is at the center: orchestrates, filters, contextualizes, decides. Without them, friction is chaos. With them, it produces better decisions.

Positioning

SOFIA is not a framework, not a library, not a tool. It is a method: a set of principles, protocols, and references for organizing specialized AI assistants around a project.

The H2A protocol defines the human-assistant coordination layer. It sits alongside existing technical protocols:

H2A is not a technical protocol — it defines the semantics of interactions, not their implementation.

2. Architecture principles

P1 — Core holds without tools

The 7 principles and the conceptual model are independent of Claude Code. You could apply SOFIA with text files and an editor. The provider is an accelerator, not a prerequisite.

P2 — Five layers + canvas

You can change the binding without touching the protocol. You can change the provider without touching the binding. You can read the core without knowing the tool.

P3 — The orchestrator is the sole passage point

No direct exchange between personas. The orchestrator filters, reformulates, contextualizes, decides. This is the cost of quality.

P4 — Isolation creates the need for artifacts

A persona that cannot see the code is forced to specify. A persona that does not decide architecture is forced to surface frictions. Isolation is not a limitation — it is the generative mechanism.

P5 — Files are the source of truth

Not conversations, not memory, not compressed sessions. Versioned files in git.

P6 — Activation gradient

Start small, add structure when the orchestrator's mental load demands it.

P7 — Semantics first, binding second

The protocol defines the what (entities, invariants, operations). The binding defines the how (Markdown, git, filesystem). This separation enables:

• Mechanical audit of the protocol layer
• Changing stack without changing method
• Reasoning about the protocol without drowning in rendering details

3. Architecture — 5 layers + canvas

Five layers in the product repo, plus a transversal canvas layer.

sofia/
├── core/              ← method invariants (principles, model, duties)
├── protocol/          ← H2A protocol (invariants, operations, entities)
├── binding/           ← current materialization (filesystem, audit, scaffolding)
├── provider/          ← provider adapters (claude-code, sofia.md)
├── canvas/            ← instantiation references + inspiration tools
│   ├── archetypes/    ← persona models by role
│   ├── artifacts/     ← what a note, review, session looks like...
│   ├── patterns/      ← recurring structures observed in the field
│   ├── workflows/     ← standard processes
│   └── examples/      ← katen/ (field instance snapshot)
└── doc/               ← documentation, feedback, ADR, figures

core/ — why SOFIA exists

The invariants. Remove them and it is no longer SOFIA.

Versioning rule: modifying a core document = minor bump.

protocol/ — what to trace (auditability contract)

4 documents. H2A protocol + 3 operational specs. English filenames (i18n). What the audit reads cross-instance.

5 H2A invariants:

1. Constitutive friction
2. Human arbiter
3. Isolation
4. Traceability
5. Residual opacity (structural limitation, not a capability)

Protocol / observational distinction:

binding/ — how it materializes

Separated from semantics (protocol/) to allow other materializations (REST API, DB...). The distinction: "friction carries 5 dimensions" is protocol; "friction is a Markdown line with symbol + keyword + initiative" is binding.

provider/ — with which tool

The only point that changes when porting SOFIA to another AI assistant. Replaceable without touching core/, protocol/, or binding/.

Multi-provider (v0.4): provider/mistral/, provider/gemini/, etc. In-repo, not separate repos (ADR-010).

canvas/ — what it looks like

Not prescription — inspiration. Draw from it, don't copy.

The binding:filesystem tag distinguishes what is tied to the current binding from pure method content.

doc/ — how to organize

Everything else. Recommended, not required.

4. Conceptual model

MCD — 7 constitutive entities

7 entities, organized in 3 levels. Ref: core/model.md.

Entities

Relations

Formalization layers

The protocol/observational distinction traverses the MCD:

Exchange flows

Everything goes through the orchestrator. Two patterns:

Session (persona ↔ orchestrator)

1. The orchestrator opens a session with a persona
2. Direct exchange — dialogue, arbitration, decisions
3. Friction is traced in the session with markers
4. The persona writes the summary in sessions/

Message (persona ↔ persona)

1. Persona A deposits an artifact in shared/ (note, review, feature)
2. The orchestrator reads, decides to route
3. The orchestrator opens a session with Persona B and presents the artifact
4. Persona B reads, responds, deposits their response in shared/
5. The orchestrator routes the response to Persona A in a subsequent session

Personas never talk directly. The orchestrator is the human router of all exchanges. Friction emerges at each step.

SOFIA Instance

The sofia.md file at the root identifies the repository as an instance and links to the method.

Two instance types:

• Operational — long-duration, cumulative memory, produces business deliverables
• Audit — ephemeral, no inter-cycle memory, 1:1 mirror challengers, destroyed after synthesis

Sofia mounts both types from the product. It has no workspace in instances — its exteriority is the condition of its objectivity (ADR-009).

5. Multi-provider portability

Current architecture

core/ and protocol/ are provider-agnostic. binding/ is potentially multi-stack. provider/ is the only variation point per provider. Adding a provider = adding provider/mistral/, etc.

Strategy (ADR-010)

Everything in the same repo. No separate repos per platform (supersedes ADR-004).

provider/
├── claude-code/       ← reference provider
├── mistral/           ← v0.4 target (summer 2026)
└── gemini/            ← if relevant

Prerequisite: v0.3 user feedback. Do not anticipate without feedback.

The binding/provider distinction is structural:

• binding/ answers "how are artifacts stored and audited" (filesystem, API, DB)
• provider/ answers "how does the persona receive instructions and persist context" (CLAUDE.md, MISTRAL.md)

6. Decisions

Architecture decisions are tracked in ADR records.

Current binding. This document describes the method's architecture — not its tooling. For materialization details (stack, operations → concrete gestures mapping, audit, scaffolding, dashboard): see binding/implementation.md and binding/filesystem/.

Aurele — 17/04/2026