architecture
The seven-layer architecture
Every partyclip deployment is built on the same seven layers. Each layer is a clean interface: a layer never knows about the layers above it. The lower layers are immutable substrate; the upper layers are where the world reaches in. What changes between deployments is the configuration on top — constitutions, ministries, agent personas, and branding.
The walkthrough below goes bottom-up, from the foundation to the public surface. Select a layer above to jump to it.
Layer 0
Constitutional Layer
The immutable substrate of a deployment. Every patch the system produces is evaluated against it, and nothing above this layer can quietly change it.
What lives here
- ConstitutionArticle entities with stable IDs (e.g. CONST-K1-A2.1) — the charter, bylaws, and red lines a deployment commits to.
- A per-article mutability setting: immutable, amendable by simple majority, by supermajority, or only by referendum.
- The citation contract — every patch must reference the articles it touches, with a declared relevance.
Why it's a separate layer
L0 is the only layer with nothing beneath it. Every layer above cites it; it cites nothing. The constitution is never edited in place — amendments enter only as constitution-classified patches routed through the supermajority pipeline, and an attempt to alter an immutable article is a hard validator block, recorded in the audit log. Keeping the constitution as its own layer is what makes "the rules changed" always visible.
- CONST-K1-A2.1 — Right to algorithmic transparency
- mutability: AMENDABLE_SUPERMAJORITY
- a citing patch must declare: supporting | tension | opposing
Layer 1
Party Organs
The political will of the deployment — the actors who decide what the party stands for. partyclip ships the roles as generic primitives; each deployment names and sizes them.
What lives here
- A leader role — the single accountable head of the party.
- A central committee and policy councils — the deliberative bodies.
- A parliamentary group — the organ that carries positions outward.
- Per-deployment configuration of each organ's name, size, and decision authority.
Why it's a separate layer
L1 is the party; L2 is the government it shadows. They are tightly coupled — in most deployments a party organ head also fronts a shadow ministry — but they answer different questions. L1 decides what the party wants; L2 decides what it would do if it held office. Splitting them keeps the party's position and the executive's plan from collapsing into one undifferentiated voice.
- leader
- central-committee
- policy-council
- parliamentary-group
Layer 2
Shadow State
A one-to-one mirror of the real government's ministerial structure — the deployment's model of what it would do in power.
What lives here
- A shadow leader — a president- or prime-minister-equivalent.
- Shadow ministries, each mapped to a real-world counterpart.
- Policy boards that group ministries by domain.
- The mapping itself, defined in the deployment's content repository.
Why it's a separate layer
The mirror is deliberately one-to-one. The public-facing Contrast widget — a real ministry beside its shadow — is one of a deployment's most legible outputs, and it only works if every real ministry has exactly one shadow counterpart. L2 is kept apart from L1 because executive structure follows the real state, while party structure follows the party; forcing them into one layer would distort both.
- shadow: Ministry of Economy
- mirrors: Ministry of Treasury and Finance
- shown side-by-side in the Contrast widget
Layer 3
Work Products
What the system actually produces — the artifacts a deployment publishes and is judged on.
What lives here
- Patch — the atomic policy artifact, the unit that flows through the pipeline.
- PressRelease — a spokesperson-generated announcement, published alongside its patch.
- Counter-Bill — a patch drafted in response to a real government action.
- Manifesto — assembled from approved patches by the manifesto-builder plugin.
- Dissent — a first-class minority opinion any agent can attach at any stage.
Why it's a separate layer
L3 is the noun; L4 is the verb. A patch is an artifact with an identity and a history of its own, independent of where it currently sits in the pipeline. Keeping the artifacts separate from the process that moves them means a published patch, its dissents, and its press release stay stable, citable records even as pipeline rules evolve.
- Patch
- PressRelease
- Counter-Bill
- Manifesto
- Dissent
Layer 4
Governance & Audit
The control layer — the gates every work product passes through before it reaches anyone. Enforced by the framework itself, not by the deployment.
What lives here
- The patch pipeline — a state machine whose stages are each a separate agent run.
- Voting — a binary vote at the critic stage, a multi-head cabinet vote for larger patches.
- The Bias Mirror — an adversarial review stage that surfaces inherited assumptions.
- Operator sign-off — the mandatory final gate; operators may intercept earlier, but may only approve at the end.
- An event-sourced, append-only audit log.
Why it's a separate layer
L4 is the load-bearing safety layer, so it is owned by the framework and cannot be disabled by a deployment's configuration. It sits between the artifacts (L3) and the outside world (L5 and L6): nothing produced inside the system becomes public without passing through it, and every decision it makes — every vote, override, and sign-off — becomes a permanent event.
- DRAFTING
- CRITIQUE
- RISK_ASSESS
- EXECUTOR
- BIAS_MIRROR
- AWAITING_SIGNOFF
- PUBLISHED
Layer 5
External Inputs
Everything that enters from outside the agent loop — citizens, news, government actions, money — normalized before any agent sees it.
What lives here
- Citizen-opened issues from registered users.
- Forum threads, read only by an isolated ingestor agent.
- News ingestion, via a first-party plugin.
- A government-action monitor that emits an event when the real state acts.
- Donations, through pluggable payment processors.
Why it's a separate layer
External input is untrusted input. L5 exists so that nothing from outside reaches an agent as raw text: every input becomes a typed event on the bus and passes through a structured ingestor first. The forum in particular is read by a sandboxed agent with no tools that emits only typed summaries — making the system prompt-injection-resistant by construction rather than by vigilance.
- news.ingested
- issue.opened
- gov_action.detected
- forum.feedback_summary.updated
- budget.threshold_crossed
Layer 6
Public Surface
Where a deployment meets the world — the same content, exposed differently to anonymous readers, registered citizens, and operators.
What lives here
- The public site — blog-style, anonymous reads, captcha-gated anonymous comments.
- The internal surface — registered-only, with forum and pipeline visibility gated per tier.
- A composable homepage, assembled from a universal widget set in deployment config.
- Time-delayed visibility rules, so a free tier can see earlier-stage outputs after a set delay.
Why it's a separate layer
Presentation is configuration, not core. The widget set — intro, latest published, in-flight patches, cost dashboard, contrast, donations — is universal; what each deployment chooses is which widgets to show and in what order. Keeping the public surface as its own layer means a deployment can change how it looks to the world without touching the governance, artifacts, or constitution beneath it.
- Intro · LatestPublished · InFlight
- Manifesto · CostDashboard · Contrast
- Issues · Donation · PressFeed · Badges · Events
Cross-cutting
The event bus and the audit log.
Two concerns run through every layer rather than sitting in one. The event bus carries every meaningful action as a typed event — a pipeline stage completing, a vote session opening, a petition crossing its threshold — and each agent subscribes to the events that should wake it.
The audit log records all of it, append-only. An override is an event; a dissent is an event; a sign-off is an event. Any historical state can be reconstructed by replaying events from genesis. The log is the truth; the database is only a cache of it.
This page is the overview. The canonical, evolving reference is the framework repository on GitHub — see docs/architecture.md and docs/data-model.md.