Monorepo and Workspace Structure
Relevant source files
The following files were used as context for generating this wiki page:
Opificia organizes its codebase as a monorepo managed by pnpm. This structure consolidates the software factory's core server logic, web interface, software development kits (SDKs), and external integrations into a single repository to ensure consistency across the agentic loop.
The repository uses workspace filtering to manage dependencies and build processes for specific components. Each functional area within the monorepo adheres to specific licensing and architectural rules defined in the project's foundation files.
Sources: AGENTS.md:12-16, AGENTS.md:89-91, README.md:46-51
Workspace Components
The Opificia monorepo divides code into applications, SDKs, and plugins. These components work together to facilitate the "loop" where agents turn tickets into tested pull requests.
Core Applications
Core applications reside in the apps/ directory. They provide the primary execution environment and user interface for the software factory.
apps/server: Executes the decider logic, manages Prisma migrations, and coordinates runs.apps/web: Provides the React-based dashboard for reviewing agent progress and approving plans.
SDKs and Contracts
Shared logic and protocols live in the sdk/ directory. These packages define how different parts of the system communicate.
sdk/contracts: Defines the runner protocol and shared types used by both the server and harnesses.sdk/runner: Contains the logic for executing agent tasks in sandboxed environments.
Plugins and Extensions
The plugins/ directory contains optional integrations with external AI models or platforms.
plugins/harness-claude: The first implemented harness, integrating Claude Code into the Opificia factory.
Sources: AGENTS.md:89-91, AGENTS.md:95-97, README.md:46-51
Architectural Relationships
The following diagram illustrates the relationship between the various workspace members and how data flows through the monorepo components during a typical agent run.
The diagram shows that sdk/contracts acts as the central interface definition for all other components.
Sources: AGENTS.md:89-100, apps/web/src/run/conversation.tsx:3-33
Workspace Configuration and Tooling
Opificia utilizes a specific toolchain to manage the monorepo environment, requiring Node.js 24 and pnpm 12.
| Task | Command | Description |
|---|---|---|
| Installation | pnpm install | Installs dependencies across all workspace members. |
| Build | pnpm build | Builds all packages and generates the Prisma client. |
| Testing | pnpm test | Runs Vitest suites for all packages. |
| Typecheck | pnpm typecheck | Validates TypeScript types across the monorepo. |
| Filtering | pnpm --filter <pkg> <cmd> | Executes a command on a specific workspace member. |
Sources: AGENTS.md:89-95, AGENTS.md:104-108
Licensing and Governance by Folder
The monorepo enforces a strict licensing model where the license type depends on the specific folder. This ensures the "Inbound equals outbound" policy for contributions.
The diagram represents the license distribution as mapped in the project's REUSE configuration.
Sources: REUSE.toml:13-52, CONTRIBUTING.md:162-171
Licensing Summary Table
| Folder Path | License Identifier | Usage Context |
|---|---|---|
** (Default) | AGPL-3.0-only | Core factory logic and server implementation. |
sdk/**, plugins/** | Apache-2.0 | Extension points for easier adoption and integration. |
docs/**, website/** | CC-BY-4.0 | Documentation prose and static website content. |
*.yml, .github/** | CC0-1.0 | Configuration and CI/CD templates. |
brand/** | Opificia-Trademark | Protected brand assets (not open source). |
Sources: REUSE.toml:13-75, README.md:46-51
Development Workflow
Developers interact with the monorepo through a unified command-line interface. When modifying a specific application, such as the web app, developers must build the dependent contracts first.
- Dependency Installation:
pnpm installresolves all internal workspace links. - Component Isolation: Use
--filter @opificia/webor--filter @opificia/contractsto limit the scope of build or test actions. - Database Management: Prisma migrations are managed via
pnpm db:migratefrom the root, affecting the server application. - Validation: CI checks include license linting (REUSE), Markdown style, and link validation across all folders.
Sources: AGENTS.md:92-101, AGENTS.md:104-106, AGENTS.md:126-140
Conclusion
The Opificia monorepo structure supports the project's goal of transparency and self-hostability. By centralizing core logic, SDKs, and plugins, the project maintains strict architectural control and licensing compliance while allowing for model-agnostic extensions through its internal workspace boundaries.