Web Application Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Opificia web application provides a user interface for operators to monitor and control AI agents as they transform tickets into pull requests. The application displays real-time run data, implementation plans for human approval, and detailed logs of agent activities within sandboxed environments. It serves as the primary interface for the human-in-the-loop review process required before any code is merged.
Sources: AGENTS.md:16-20, apps/web/package.json
Architecture and Stack
The web application is built as a TypeScript project using React 19 and Vite. It utilizes a pnpm workspace structure and connects to a NestJS server via a REST API and Server-Sent Events (SSE).
Core Technologies
| Category | Technology |
|---|---|
| Framework | React 19 |
| Build Tool | Vite 8 |
| Routing | TanStack Router |
| Data Fetching | TanStack Query |
| Styling | Tailwind CSS 4 |
| Authentication | Better Auth |
| Type Safety | Zod |
| Icons | Lucide React |
Sources: apps/web/package.json:20-35, AGENTS.md:16-20
Application Components
The following diagram illustrates the high-level data flow between the Web App, the Server, and the Fixture mode used for development.
This diagram shows how the React UI interacts with the backend through standard API calls and real-time event streams.
Sources: apps/web/fixtures/plugin.ts:98-150, apps/web/src/run/conversation.tsx:645-660
Run Lifecycle and Conversation View
The central feature of the web application is the Conversation component, which visualizes the lifecycle of an agent's work on a specific issue. It organizes events into logical stages: Plan, Implement, and Result.
Event Processing
The application processes RunEventDto objects to build a timeline. Key event types include:
run.queued: The initial state when a task is created.stage.started: Marks the beginning of a specific work phase.agent.tool: Details specific actions taken by the agent (e.g., reading files, running bash commands).plan.proposed: Triggers the display of an implementation plan for human review.implementation.finished: Indicates the agent has completed the requested changes.checks.completed: Displays the results of automated security and hygiene checks.
Sources: apps/web/src/run/conversation.tsx:490-550, apps/web/fixtures/runs.ts:25-50
Human-in-the-Loop Integration
Human intervention is facilitated through specific UI cards within the conversation flow:
- PlanCard: Displays the Markdown plan generated by the agent. It includes a cost estimate in USD and requires human approval before implementation starts.
- ChecksCard: Summarizes findings from the runner, such as protected path violations, secrets detection, or hidden unicode characters.
- PullRequestCard: Provides a direct link to the generated GitHub pull request once checks pass.
Sources: apps/web/src/run/conversation.tsx:210-230, apps/web/src/run/conversation.tsx:325-340, apps/web/src/run/conversation.tsx:405-420
Development and Fixture Mode
The application includes a specialized "Fixture Mode" that allows developers to test the UI without a live backend.
Vite Fixture Plugin
The fixtures() plugin in vite.config.ts intercepts /api requests and returns recorded data from runs.ts. This mode supports:
- Mock Authentication: Returns a static session for a user named "Ada Lovelace".
- Scenario Simulation: Supports different run states including
planning,implementing,pr_opened,failed, andcancelled. - Real-time Simulation: Uses a heartbeat interval to simulate an open SSE stream.
Sources: apps/web/fixtures/plugin.ts:15-60, apps/web/fixtures/plugin.ts:115-130
Automated Screenshots
A script utilizes Playwright to capture the web app in various states. This allows developers to verify layout and theme (light/dark) compatibility.
This sequence shows how the screenshot utility orchestrates the headless browser and fixture server to document UI states.
Sources: apps/web/scripts/screenshot.ts:40-80, apps/web/scripts/screenshot.ts:110-130
Security and Constraints
The web application enforces specific security policies through its components:
- Markdown Sanitization: The
Markdowncomponent (lazy-loaded) handles rendering of agent messages and plans. It is tested to ensure it does not render raw HTML<script>tags or load external images that could be used for data egress. - Network Isolation: The fixture mode and screenshot tools are designed to work without outbound internet access, adhering to the project's sovereignty commitments.
- DCO Enforcement: Contributions to the web app require a Developer Certificate of Origin (DCO) sign-off, which is checked by automated hygiene workflows.
Sources: apps/web/src/markdown.test.tsx:15-35, AGENTS.md:35-40, CONTRIBUTING.md:40-50
Summary
The Opificia web application is a React-based monitoring and control interface. It visualizes agent work through a structured conversation timeline, manages human approvals for implementation plans, and reports on automated security checks. Through its fixture mode and comprehensive testing suite, it enables reliable development and auditing of AI-driven software automation while maintaining strict data sovereignty and security standards.