ARCHITECT.md

System Shape

Contributors Community is a pnpm/turbo monorepo with a domain-first backend, a Next.js product UI, and an MCP bridge for agent-connected project intake.

flowchart LR
  Browser["Browser / user"] --> Web["apps/web Next.js"]
  Agent["Codex / Cowork / MCP client"] --> Mcp["apps/mcp stdio server"]
  Web --> Api["apps/api NestJS /api/v1"]
  Mcp --> Api
  Api --> Auth["Auth context + policy gate"]
  Auth --> Application["packages/application use cases"]
  Application --> Domain["packages/domain aggregates"]
  Application --> Ports["Repository and provider ports"]
  Infrastructure["packages/infrastructure"] --> Ports
  Infrastructure --> Events["PostgreSQL domain_events"]
  Events --> Projections["Rebuildable projections"]
  Web --> AuditRoom["Audit Room markdown + Mermaid rendering"]
  Domain --> Source["Project source connection metadata"]
  Source --> AuditRoom

Trust Boundaries

• Browser sessions are converted into signed trusted-principal headers when a server secret exists.
• MCP production calls must also sign trusted-principal headers.
• Development headers are accepted only outside production.
• Policy checks happen in the API before application use cases run.
• Privileged roles require MFA.

Domain Boundaries

• Projects own charters, project-source connections, and signing state.
• Missions own publish requirements and deliverable scope.
• Applications own contributor intent and withdrawal.
• Acceptance owns human acceptance decisions.
• Ledger owns points and corrections as append-only events.
• AI Assist owns non-binding interactions and human confirmation/rejection.
• Disputes own stage-one decisions.
• Privacy owns data subject request intake.

Source And Audit Room

Project source connections are metadata-first. A project can reference Codex, Cowork, GitHub, uploads, or manual artifacts without granting broad repository access by default.

The Audit Room renders source documents such as:

• README.md
• ARCHITECT.md
• VISION.md
• additional artifacts listed in contributors.project.json

Mermaid diagrams are rendered client-side in the web app.

Runtime Packages

• apps/web: UI, auth/session flow, role-aware project surfaces.
• apps/api: API routes, auth context, policy enforcement, lifecycle facade.
• apps/mcp: JSON-RPC over stdio and API forwarding for agent tools.
• packages/api-contracts: Zod contracts shared by web, API, and MCP.
• packages/domain: pure domain model and events.
• packages/application: orchestration use cases.
• packages/policies: CASL-based role and MFA rules.
• packages/infrastructure: persistence and projections.

Persistence Model

Domain events are append-only and hash-linked in PostgreSQL. Projections are rebuildable read models, not the source of truth. Ledger corrections are modeled as new events instead of mutation.

Contributors Vision

Stand: 2026-05-13 Status: Root-Synthese aus Strategiepapier, Vision-Update und Project-Manifest Owner: Tim Mergenthaler

Beitrag vor Kapital. Ledger vor Bauchgefuehl.

Contributors ist die Trust-, Audit- und Contribution-Schicht fuer eine AI-Aera, in der es mehr glaubwuerdige Repositories, Prototypen und Demos geben wird als belastbare Teams, klare Verantwortung und gepruefte Capabilities.

Die Plattform hilft Initiatoren, aus einem unfertigen, aber substanziellen Projekt ein pruefbares Venture-Building-Objekt zu machen: mit Charter, Audit-Room, klaren Missionen, menschlichen Entscheidungen, Contribution Ledger und spaeterer Uebersetzung von Beitrag in Upside.

These

AI macht Building moeglich, aber nicht vollstaendig.

Die neue Knappheit ist nicht Code. Die neue Knappheit ist Vertrauen, Urteilsvermoegen, Domain-Expertise, rechtliche Klarheit, technische Review-Qualitaet, Produkt-Fokus, Go-to-Market-Kompetenz und Investor-Readiness.

Contributors existiert fuer genau diese Luecke:

• Repo-born Projekte sollen lesbar und auditierbar werden.
• Fehlende menschliche Capabilities sollen als klar begrenzte Missions sichtbar werden.
• Contributions sollen vorab definiert, nachweisbar geliefert und append-only dokumentiert werden.
• AI darf vorbereiten, strukturieren und vorschlagen, aber keine bindenden Entscheidungen treffen.
• Projekte muessen nicht oeffentlich sein, um contributor-ready zu werden.

Was Contributors Ist

Contributors ist ein geschlossenes, human-gated Operating System fuer fruehe Projekte vor einem klassischen vollstaendigen Team.

Ein Projekt kann als Idee, Repository, Prototyp, MVP, private Codebase, Forschungsartefakt, AI-generierter Build oder Founder-led Side Project starten. Contributors fragt nicht, ob es schon fertig ist. Contributors fragt:

• Was existiert bereits?
• Welche Quelle ist pruefbar?
• Was bleibt privat?
• Welche Artefakte duerfen in den Audit-Room?
• Welche kritische Capability fehlt jetzt?
• Welche Mission ist so klar, dass ein Mensch sie annehmen, liefern und reviewen kann?
• Welche Risiken muessen vor Oeffnung, Contribution oder Pilot sichtbar sein?

Das Produkt ist deshalb zuerst ein Trust-Substrat, nicht ein Marketplace.

Was Contributors Nicht Ist

Contributors ist in Phase 1 bewusst nicht:

• ein oeffentlicher Self-Service-Marktplatz,
• ein Freelancer-Marktplatz,
• eine DAO,
• ein Cap-Table-Tool,
• eine Crowdfunding-Plattform,
• ein Ort fuer AI-only-Decisions,
• ein Versprechen auf automatische Equity,
• ein Zwang, private Repositories zu oeffnen.

Die spaetere Vision kann Project Value, Project Fund und Cash-Hybrid-Missions enthalten. Die Phase-1-Doktrin bleibt konservativ: Recht vor Produkt, Audit vor Geschwindigkeit, Mensch vor AI.

Operating Model

1. Project Charter

Der Initiator legt ein Projekt an und beschreibt Stand, Ziel, Sichtbarkeit, Risiken und erste Artefakte. Der Charter ist die Grenze zwischen Idee und operativem Contributors-Projekt.

Ohne unterschriebenen Charter keine Mission. Ohne counsel-faehige Templates kein echter Pilot.

2. Source Connection

Ein Projekt kann mit einer Quelle verbunden werden: Codex Workspace, Cowork, GitHub, Upload oder manual Concierge Intake. Die Quelle ist kein Freibrief fuer Repository-Zugriff.

Das Project Manifest ist der Handoff-Vertrag:

{
  "manifestVersion": "contributors.project@1.0.0",
  "source": {
    "provider": "codex",
    "visibility": "selective",
    "scopes": ["metadata", "read_artifacts"]
  },
  "artifacts": ["README.md", "VISION.md", "ARCHITECTURE.md", "docs/audit/AUDIT.md"]
}

Guardrail: Kein Repository wird implizit gelesen. Nur explizit freigegebene Artefakte werden als Audit-Room-Kontext genutzt. Secrets, private Branches und unveroeffentlichte Unterlagen bleiben ausgeschlossen, bis ein menschlicher Initiator passende Scopes gewaehrt.

3. Audit Room

Der Audit-Room macht das Projekt pruefbar, ohne es komplett oeffnen zu muessen.

Standard-Artefakte sind:

• README.md fuer Produkt- und Repo-Kontext,
• VISION.md fuer Zielbild, Doktrin und Grenzen,
• ARCHITECTURE.md fuer Systemgrenzen, Datenfluesse und Risiken,
• AUDIT.md fuer Reifegrad, Lead Ask, Risiken und Contribution-Slots.

Wenn echte Source-Artefakte existieren, gewinnen sie. Wenn sie fehlen, darf ein klar markierter Fallback aus dem Projektprofil helfen, aber niemals so tun, als sei er Repo-Quelle.

4. Missions

Eine Mission ist ein begrenztes Work-Paket mit Ziel, Deliverable, Kontext, Akzeptanzkriterien, Risiko, Review-Owner, Contribution-Point-Wert und IP-/Confidentiality-Anforderungen.

Contributions sind breiter als Pull Requests:

• Build Contributions,
• Expert Contributions,
• Strategic Contributions,
• Trust Contributions,
• Network Contributions.

Der entscheidende Unterschied zu Freelance-Arbeit: Nicht Zeit wird verkauft, sondern nachweisbarer Wertbeitrag wird dokumentiert.

5. Human-Gated Acceptance

AI kann Akzeptanzkriterien vorbereiten, Risiken markieren und Vergleichsmasstaebe vorschlagen. Bindend wird eine Entscheidung erst, wenn ein benannter Mensch sie trifft.

Bei Streit gibt es drei Stufen:

1. Standardbewertung durch Initiator gegen Akzeptanzkriterien.
2. Peer Review durch passende Reviewer.
3. Externes Schiedsverfahren bei substantiellen Streitigkeiten.

6. Contribution Ledger

Das Ledger ist append-only. Es dokumentiert Missions, Deliverables, Acceptance, IP-Status, Disputes, AI-Vorschlaege, menschliche Entscheidungen und Contribution Points.

Contribution Points sind zunaechst keine Wertpapiere. Sie sind strukturierte Beitragsaufzeichnungen, die spaeter unter expliziten Vertragen in Equity, Revenue Share, Phantom Shares, Token oder andere Ansprueche uebersetzt werden koennen.

Tim's Portfolio Als Erster Kontrollierter Test

Contributors ist die Klammer, die Tim's halbfertige, aber echte Projekte zu einer ehrlichen Komposition macht. Die Unfertigkeit ist kein Makel der Demo. Sie ist der Grund, warum Contributors existiert.

Diese Komposition ist eine Lesebrille, kein Voraus-Versprechen. Jedes Projekt bleibt in seinem realen Reifegrad sichtbar.

Doktrin

• Recht vor Produkt.
• Audit vor Geschwindigkeit.
• Domain vor Framework.
• Mensch vor AI.
• Klarheit vor Eleganz.
• Reversibel vor optimal.
• Geschlossen vor offen.
• Keine Mission ohne Charter.
• Keine Contribution ohne Akzeptanzkriterien.
• Keine Points ohne Evidenz.
• Keine AI-Entscheidung ohne menschliches Gate.
• Keine oeffentlichen Claims ohne pruefbare Quelle.

ICP Und Phase-1 Scope

Initiatoren: Menschen mit einem auditierbaren Artefakt und einer benennbaren Capability-Luecke. Das Artefakt kann ein Prototyp, Early-MVP, Repository, Konzept, Datenraum, Research-Stand, Design, Workflow oder anderes belastbares Ausgangsmaterial sein. Entscheidend ist, dass die Luecke als Mission beschrieben und spaeter geprueft werden kann.

Contributors: Spezialisten, die gegen Points statt Stunden arbeiten und ihren Beitrag auditierbar nachweisen wollen. Der Fokus liegt auf Trust + Expert Missions: Counsel, Security Review, Domain Expertise, Senior Engineering Review, GTM, Research, QA, Design Review, Moderation, Operations, Community und weitere klar begrenzte fachliche Beitraege.

Expert Auditors: Counsel, Security Reviewer, Domain Experts, Senior Engineers, GTM-Experten, Mediatoren, Localization Reviewer, Compliance-Reviewer fuer weitere Jurisdiktionen, AI-Pipeline-Reviewer und andere High-Trust-Roles, deren Review ein Projekt glaubwuerdiger macht, ohne dass das gesamte Repo oeffentlich werden muss.

DACH bleibt fuer Phase 1 ein Operational Scope, kein dauerhaftes ICP-Limit. Der Pilot startet dort, wo Netzwerk, Rechtsannahmen und manuelle Concierge-Schritte am belastbarsten sind. Die Vision bleibt international und domain-agnostisch, solange Artefakt, Luecke, Gate und Acceptance auditierbar sind.

Roadmap

Quellen

• docs/strategy/vision.md
• docs/strategy/vision-update-2026-05-13.md
• docs/strategy/vision-update-2026-05-06.md
• docs/strategy/contributors-strategy-updated-repo-to-series-a.md
• docs/integrations/contributors-project-manifest.md
• docs/showcase/contributors.md
• docs/briefs/codex-brief-mvp.md

CLAUDE.md

This file gives Claude, Codex, and other coding agents the current operating context for this repository.

Mission

Contributors Community is a domain-first MVP for a contributor platform with Phase 1 DACH operational scope. The product must stay legally careful, human-gated, and auditable while still being useful as a working web app.

Non-Negotiables

• Keep domain invariants in packages/domain before HTTP, UI, persistence, or agent layers.
• Do not let AI create binding domain state on its own. AI output is advisory until a human confirms

or rejects it.

• Keep admin separate from project roles. Admin is a capability flag; initiator and contributor are

contextual relationships to projects.

• Preserve MFA checks for privileged roles.
• Use signed trusted-principal headers in production. Dev auth headers are only for non-production.
• Keep source connections explicit: provider, scopes, visibility, artifacts, and human actor.
• Prefer focused changes and tests over broad refactors.
• Do not move unrelated docs into the repo root. Root docs are limited to README.md,

CLAUDE.md, ARCHITECT.md, and VISION.md; canonical supporting docs live under docs/.

Workspace Map

• apps/web: Next.js UI, auth flow, role workspaces, project intake, Audit Room, discussions.
• apps/api: NestJS API and policy-protected lifecycle routes.
• apps/mcp: MCP stdio bridge for agent-driven project and Audit Room sync.
• packages/domain: aggregates, value objects, events, and invariants.
• packages/application: use cases and repository/provider ports.
• packages/infrastructure: event store, migrations, projections.
• packages/policies: role, MFA, and project-membership policy checks.
• packages/api-contracts: Zod request contracts shared by API, web, and MCP.
• packages/ui: shared UI primitives and compliance components.

Current Integration Points

• Web calls the API with trusted principal headers when a signing secret is configured.
• API falls back to development auth headers only outside production.
• MCP calls the API over stdio-driven tools and requires a production signing secret in production.
• Project source manifests are documented in

docs/integrations/contributors-project-manifest.md.

• MCP usage is documented in docs/integrations/contributors-mcp-server.md.

Common Commands

corepack pnpm install
corepack pnpm typecheck
corepack pnpm lint
corepack pnpm test
corepack pnpm --filter @contributors/mcp build
corepack pnpm --filter @contributors/mcp test

Run focused package checks during development, then run the repo gates before committing when the change crosses package boundaries.

Documentation Rule

If code changes alter product flow, auth, project source sync, domain events, or architecture, update the relevant docs in the same phase:

• README.md
• ARCHITECT.md
• VISION.md
• docs/architecture/*
• docs/integrations/*
• docs/README.md when a new documentation area appears

Contributors Project Manifest

contributors.project.json is the agent handoff contract for attaching an existing project to Contributors without granting broad repository access by default.

Purpose

Codex, Cowork, GitHub imports, and manual export bundles can use the manifest to create a project source connection during Project Charter setup. The manifest does not publish anything by itself. It records provenance, requested scopes, visibility, and the first reviewable artifacts.

Minimal Manifest

{
  "manifestVersion": "contributors.project@1.0.0",
  "name": "Der Dritte",
  "source": {
    "provider": "codex",
    "label": "Codex Workspace",
    "workspacePath": "/Users/tim/der_dritte",
    "visibility": "selective",
    "scopes": ["metadata", "read_artifacts"]
  },
  "artifacts": ["README.md", "VISION.md", "ARCHITECTURE.md", "docs/audit/AUDIT.md"]
}

Providers

• manual: concierge intake without a technical connector.
• codex: local or remote Codex workspace handoff.
• cowork: Cowork project handoff.
• github: repository source.
• upload: file or export bundle without live access.

Scopes

• metadata: project name, source label, provider, and status.
• read_artifacts: read selected artifacts listed in the manifest.
• read_repository: read repository content beyond listed artifacts.
• write_back: allow Contributors to write generated artifacts back to the source.
• webhook: allow future sync events.

Guardrails

Connected sources require explicit location data through url or workspacePath, except manual and upload. No repository is read implicitly. Sensitive data, secrets, private branches, and unpublished artifacts stay excluded until a human initiator grants the matching scope.

Contributors

Hinweis: Dieses Dokument ist ein deploybarer Fallback aus dem Contributors-Projektprofil. Sobald eine Projektquelle README, Vision oder Architektur liefert, wird sie hier bevorzugt gerendert.

Audit Snapshot

Beitrag vor Kapital, Ledger vor Bauchgefühl: Contributors macht fehlende kritische Fähigkeiten als begrenzte Missionen sichtbar.

Reifegrad

• Vorhanden: Auth-Grundlage, App-Shell, Projektübersicht, Missions- und Ledger-Mock, Compliance-Badges.
• Fehlt: Counsel-Entscheid, Contributor Agreement, Mission-Template-Review, initialer Reviewer-Pool.

Lead Ask

DACH-Plattform-Counsel: Juristische Erstprüfung für Charter, Contributor Agreement, Mission Value, CP-Ledger, Dispute-Grundlogik und geschlossenen DACH-Pilot.