System Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Opificia AI is an open-source software factory that automates the software development lifecycle using AI agents. The system enables agents to pick up tickets from a tracker, write code changes in a sandbox, run test suites, and open pull requests for human review. It is built with a focus on digital sovereignty, ensuring that operators can host the entire stack, including AI models, on their own infrastructure without mandatory external dependencies.
Sources: README.md:3-7, website/index.html:43-47, publiccode.yml:25-27
Core Development Loop
The architecture implements a five-step loop that moves a task from a ticket to a merged pull request. This process maintains human control at the final stage to ensure code quality and security.
The diagram shows the sequence of operations from the initial ticket description to the final human approval and merging.
Sources: website/index.html:56-82, README.md:12-16
Architectural Components
The project uses a pnpm workspace to manage multiple internal components and external extensions. The target stack includes TypeScript, Node.js 24, NestJS, and PostgreSQL.
System Modules
| Component | Location | Responsibility |
|---|---|---|
| Server | apps/server | Handles the run lifecycle, decider logic, and database migrations. |
| Web App | apps/web | Provides the user interface for monitoring runs, plans, and approvals. |
| Contracts | sdk/contracts | Defines the runner protocol and shared API types. |
| Runner | sdk/runner | Executes agent tasks within a controlled environment. |
| Harnesses | plugins/harness-* | Adapts specific AI models (e.g., Claude) to the Opificia runner protocol. |
Sources: AGENTS.md:11-14, 52-54, CHANGELOG.md:18-20
Digital Sovereignty and Security
The architecture is governed by eight sovereignty commitments that dictate how the system handles data and external connections.
Commitment Implementation
- Self-Hosting: Every feature must work without outbound internet access.
- Model Agnostic: The system communicates with models via open, documented interfaces, supporting open-weight models as first-class citizens.
- Sandbox Isolation: Agents operate in sandboxed environments with configurable network egress policies.
- Telemetry: Telemetry is disabled by default and only connects to operator-configured endpoints.
Sources: SOVEREIGNTY.md:17-46, publiccode.yml:29-37
Egress Control Flow
The diagram illustrates how the egress proxy intercepts agent network requests based on the local configuration.
Sources: SOVEREIGNTY.md:17-25, CHANGELOG.md:18-20, plugins/harness-claude/src/prompts.ts:7-12
Agent Logic and Prompting
Harnesses translate repository tasks into structured prompts for AI models. The harness-claude plugin provides a reference implementation for this interaction.
Prompt Structures
- Plan Prompt: Instructs the agent to read the code and propose a summary, file changes, and test strategies.
- Implement Prompt: Directs the agent to execute the approved plan, modify files, and fix failing tests.
- Review Prompt: Forces the agent to review its own
git difffor bugs or missing edge cases before human submission.
Sources: plugins/harness-claude/src/prompts.ts:78-132
Network Rules Configuration
The system injects specific rules into agent prompts based on the sandbox's network level:
const NETWORK_RULES: Record<NetworkLevel, string> = {
none: "- There is no internet access. Do not try to install packages...",
registries: "- You can reach package registries through a proxy...",
open: "- You can reach most hosts over HTTPS, requests are logged...",
};
Sources: plugins/harness-claude/src/prompts.ts:7-12
Roadmap and Evolution
The project follows a phased roadmap to transition from foundational policies to a production-ready software factory.
- Phase 0 (Foundations): Governance, licensing, and sovereignty commitments.
- Phase 1 (First Loop): A single agent handling one ticket in a sandbox with a working UI.
- Phase 2 (Hardening): Implementing sandbox isolation, audit logs, and open-weight model harnesses.
- Phase 3 (First Release): Providing signed releases, SBOMs, and a European reference deployment.
Sources: ROADMAP.md:10-54, website/index.html:139-165