10. Overall Architecture and Class Diagrams - FA-Systems-Operon/Operon GitHub Wiki

1. Purpose and scope

Operon is an internal web application that helps FA Systems move a signed client through onboarding, launch preparation, client communication and early performance review. It is built from three product layers to better represent the :

  • Brain stores what Operon knows about each client and about FA Systems standards.
  • Workforce runs bounded AI workflows that turn that knowledge into drafts.
  • Command Center controls who can do what, records approvals and audit history, and shows delivery status.

Design rules that apply everywhere:

  • AI output is always a draft. A named, authorized person approves an exact version.
  • Approval never acts outside Operon. Sending, publishing and configuring happen in other tools.
  • Source documents are evidence, never instructions.
  • The backend enforces every permission.
  • Sensitive client data never enters the repository.

2. High-level architecture

Layer Contains Responsibility
Presentation React screens Display data, collect input, call the API
Entry points API routes, worker loop Receive a request or a job, check identity, call a service
Services and domain logic Services, rules, agents Business rules, orchestration, validation
Repositories and adapters Repositories, FileStorage, ModelProvider All database access and all contact with the outside world

The worker is an entry point, like the API routes. It starts work and calls services.

3. General system lifecycle

Container Role
frontend Vite dev server serving the React app; proxies API calls to the backend
api HTTP API. Validates requests, enforces permissions, calls services
worker Background loop. Claims pending jobs, runs agents, saves drafts
db PostgreSQL 17. Business records, versions, jobs, audit events
ollama Local open-weight model, reached through the ModelProvider interface
File volume Original documents, redacted derivatives, exports

The api and worker containers are built from the same image and differ only in their start command. They never call each other. They communicate through the jobs table, so queued work survives a restart.

4. Boundaries

Brain responsibilities

Purpose: be the single, versioned source of what Operon knows. Nothing downstream uses a fact that has not passed through the Brain.

The Brain handles three kinds of information:

Information Examples Handling
FA Systems standards Delivery playbook, qualification definitions, message templates Versioned and approved
Client requirements Approved services, service area, capacity, budget, offer Structured facts with provenance and effective dates
Observed activity Uploaded conversations, launch confirmation, imported activity Timestamped evidence with freshness flags

The Brain is responsible for

  • Storing clients and their uploaded source documents, with validation, content hashes and original files.
  • Parsing documents to text and keeping source locators (page, time stamp, question number) so every fact can be traced.
  • Redacting and minimizing text before it can reach a model.
  • Storing client profile versions, playbook versions and artifact versions. Versions are never edited in place: editing an approved version creates a new one.
  • Recording where each fact came from and its status (confirmed, proposed by an agent, unknown, conflict).
  • Detecting gaps and conflicts, and keeping unknowns explicit. A missing fact is never inferred.
  • Assembling the approved context for an agent: approved profile version, playbook version, and client-scoped source excerpts.
  • Marking dependent artifacts stale when an approved profile changes.
  • Exporting approved versions.

Workforce responsibilities

Purpose: run bounded, coded AI workflows that prepare drafts from one approved context version.

The Workforce is responsible for

  • Defining the agent contract shared by every module: authorized client, approved context version, source references, input schema, output schema, model and prompt version, run budget, and a typed result.
  • Hosting the agent modules:
Agent Release Output Never
Onboarding R1 core Profile draft, conflicts, missing questions Infers budgets or promises
Launch Preparation R2 target Campaign brief, qualification instructions Installs workflows or publishes ads
Communication R2 target Message drafts for a person to send Sends, or claims an unconfirmed launch
Early Performance Final, if data allows Evidence-linked exceptions Claims ad causes or revenue
  • Persisting a job before any execution, with a job_key that is unique in the database so duplicate requests create one job.
  • Running jobs in the worker with a small, measured concurrency limit, explicit deadlines, and bounded retries for transient failures only.
  • Validating structured output against the schema, with one controlled repair attempt. Output that still fails becomes a visible, retryable failure with a short last_error. It never becomes a draft.
  • Recording every run (AgentRun): agent type, model, prompt version, duration, token usage and status.
  • Recovering jobs left in the running state after a restart.
  • Pausing new AI jobs when the configured usage limit is reached, while leaving existing data and review screens available.
  • Providing the ModelProvider interface with an Ollama implementation and a deterministic FakeProvider for tests and CI.

Command Center responsibilities

Purpose: control access, make approval an explicit recorded act, keep an audit trail, and show where each client stands.

The Command Center is responsible for

  • Authentication: invite-only accounts, login, sessions.
  • Authorization: roles and per-client access, checked on the backend for every request.
  • Approval: recording a named user's decision on an exact version, including a verdict on each critical field. Approval is blocked while a conflict is unresolved, while required fields are unreviewed, or while the output fails validation.
  • Audit: an append-only record of who did what, when, for which client and which version.
  • Delivery stages: the fixed stages Intake, Profile Review, Launch Preparation, Implementation, Launch Confirmed, Early Review, with rules rejecting invalid transitions.
  • Delivery records: actions a person did outside Operon, such as "kickoff call held" or "GHL pipeline set up".
  • Overview: clients, stages, blocking inputs, pending approvals and failed runs.
  • Administration: users, client access, model configuration, run usage and system health.
  • In-app notifications such as review badges. No email or chat integration.

Endpoints by Module

Roles: A admin, R reviewer, V viewer, Any any signed-in user. "Member" means the user has access to that client.

Command: access and administration

Endpoint Purpose Allowed
POST /auth/login, POST /auth/logout Sign in and out Anyone / Any
GET /me Current user and role Any
POST /users/invite, GET /users, PATCH /users/{id} Manage users and roles A
PUT /clients/{id}/access Grant or revoke client access A
GET /admin/usage, GET /admin/health Usage and system status A
GET /admin/model-config, PUT /admin/model-config Model settings A
GET /health Liveness for Docker only, no data Anyone

Brain: clients and documents

Endpoint Purpose Allowed
GET /clients, GET /clients/{id} List and read clients Any, member only (A sees all)
POST /clients Create a client R
POST /clients/{id}/documents Upload a source document R, member
GET /clients/{id}/documents, GET /documents/{id}/text List documents, read redacted text Any, member

Brain: profiles, playbooks, artifacts

Endpoint Purpose Allowed
GET /clients/{id}/profile-versions, GET /profile-versions/{id} Version history and detail Any, member
PATCH /profile-versions/{id} Edit a draft; on an approved version, creates a new draft R, member
GET /profile-versions/{id}/gaps, .../dependents Gaps, conflicts, dependent artifacts Any, member
GET /clients/{id}/questions, POST /clients/{id}/questions Client questions R, member (read: Any)
GET /profile-versions/{id}/export Export an approved version Any, member
GET /playbooks, GET /playbooks/{id} Read playbooks Any
POST /playbooks, PUT /playbooks/{id} Create or edit a playbook version A
GET /artifacts/{id} Read an artifact version Any, member

Workforce: agents, runs, jobs

Endpoint Purpose Allowed
GET /agents Agent catalog with status (available, planned, conditional) Any
POST /clients/{id}/runs Start a run; returns 202 and a job id R, member
GET /runs, GET /runs/{id} Run list and detail Any, member
GET /jobs/{id} Job status for polling Any, member
POST /jobs/{id}/retry, POST /jobs/{id}/cancel Retry or cancel R, member

Command: review, approval, delivery, audit

Endpoint Purpose Allowed
GET /overview Dashboard data, filtered by access Any
GET /reviews Review inbox R (A read-only)
POST /profile-versions/{id}/field-decisions Verdict on one field, with note R, member
POST /profile-versions/{id}/approve, /reject, /request-changes Decide on the exact version R, member
POST /artifacts/{id}/approve, /reject, /request-changes Same for artifacts R, member
POST /clients/{id}/delivery-records Record an action done outside Operon R, member
GET /clients/{id}/stage-history Stage changes Any, member
GET /clients/{id}/audit Audit trail for a client A, R member

Screens and the endpoints they use

Screen (mockup) Plan area Main endpoints
Command Overview /overview, /reviews, /runs
Brain Client workspace /clients/{id}, /profile-versions/*, /documents/*
Review Review inbox /reviews, /profile-versions/{id}/field-decisions, .../approve
Workforce (Bench) Agents and runs /agents, /runs, /jobs/{id}
Workforce (World) Optional Same as Bench
Playbooks Playbooks /playbooks
Administration Administration /users, /admin/*

Frontend/Backend Boundaries

  1. The frontend talks only to the backend API. It never reaches PostgreSQL, the file volume or Ollama.
  2. All endpoints are JSON over HTTP under /api/v1. File upload uses multipart/form-data.
  3. Authentication uses an HTTP-only session cookie with CSRF protection.
  4. Every endpoint checks authentication, role and client access on the backend.
  5. Actions that start AI work return 202 Accepted with a job id. The frontend polls the job.
  6. Errors use one shape: { "error": { "code": "...", "message": "..." } }. Codes used: 401 not signed in, 403 role not allowed, 404 not found or no access, 409 stale or conflicting version, 422 validation failed.
  7. IDs are opaque. Timestamps are ISO 8601 in UTC.

5.Tentative Roles/Permissions

Capability Admin Reviewer Viewer
See clients they have access to Yes (all clients) Yes Yes
Create clients, upload documents No Yes No
Edit profile drafts, answer client questions No Yes No
Start, retry and cancel runs No Yes No
Record field verdicts No Yes No
Approve or reject a version No Yes No
Record delivery events No Yes No
View audit trail Yes Yes (own clients) No
Invite users, change roles, grant client access Yes No No
Edit playbooks Yes No No
Model configuration, usage, health Yes No No
  • Reviewer is the plan's "authorized reviewer/operator".
  • Administrators do not approve implicitly. Approval is an explicit action by a user with the reviewer role.
  • Access to a client is a membership (ClientAccess). A role says what a user can do inside the clients they belong to.
  • A request for a client the user cannot access returns 404, so the response does not reveal that the client exists.

UML Class Diagram