- Forge-canonical source control and GitHub mirroring, if that remains the

  intended cutover.

### Gate 1 implementation status

Completed on 2026-08-20:

- Added `docs/architecture.md` as the source of truth for product ownership,

  durable authority, provider and trust boundaries, forge planes, deployment

  strategies, staging topology, and the source-control transition.

- Classified public, authenticated, operator, machine, internal-service, and

  Git principals. The architecture names Gate 6's exhaustive route ledger as

  the enforcement proof instead of claiming that route placement is enough.

- Added seven focused decision records for the complete public integration,

  Sarah's persona boundary, provider credentials, encrypted GitHub token

  retention, the Basecoat component system, isolated staging topology, and the

  proof-gated forge-canonical cutover.

- Recorded GitHub as the accurate temporary canonical remote during hardening.

  The forge cutover cannot occur until its Git, mirror, artifact, rollback, and

  recovery gates pass together with updated contributor automation.

**Exit criteria:** A contributor can explain the application and its trust

boundaries without reading a superseded plan or another repository.

## Final staging readiness checklist

- [ ] The repository has one accurate architecture narrative.

- [x] The repository has one accurate architecture narrative.

- [ ] Every remaining Sarah reference is intentional and specific.

- [ ] All documentation links and invariant evidence resolve.

- [ ] The application has one Markdown parser, component system, and documented

# OpenAgents architecture

Date: 2026-08-20

Status: Current product architecture and accepted hardening target

## Purpose

This document is the source of truth for the integrated `openagents.com`

application. Use it to understand product ownership, durable authority, trust

boundaries, and deployment strategies. Dated migration and implementation plans

remain useful as historical records, but they do not override this document.

OpenAgents is one public AGPL-3.0 application. It includes the source-code

forge, issues and projects, the Sarah conversational agent, provider

orchestration, memory, voice, delegated work, connected computers, and operator

surfaces. The application does not divide these features between a public shell

and a private product service.

## System map

```text

browser

  |

  | HTTPS, LiveView, WebSocket, or authenticated JSON

  v

OpenAgents Phoenix application

  |-- public and authenticated web surfaces

  |-- Sarah conversation, voice, memory, and work orchestration

  |-- issues, projects, machines, and data rights

  |-- Git HTTP and forge deployment control

  |-- server-side provider adapters

  |

  +--> PostgreSQL: durable product and deployment authority

  +--> object/artifact storage: immutable build artifacts

  +--> provider APIs: replaceable server-side dependencies

  +--> GitHub: identity and user-authorized repository access

  `--> BEAM cluster: ephemeral execution and fleet coordination

```

The `OpenAgents` namespace owns generic application infrastructure. Sarah is a

persona and behavior package within that application, not a second application

or service boundary.

## Product ownership

The repository owns these capabilities:

- Browser presentation and Phoenix LiveView state.

- Sarah persona artifacts, behavior, voice, and evaluation material.

- Conversation, message, turn, provider-step, and tool-step lifecycles.

- Provider selection, request construction, response handling, and usage

  accounting.

- Tools, memory systems, delegated work, and connected-computer orchestration.

- Accounts, data export, deletion, administrative policy, and incidents.

- Repositories, Git HTTP, issues, labels, milestones, projects, and public code

  browsing.

- Build, promotion, deployment, rollback, convergence, and deployment receipts.

Do not add a private Sarah service as an architectural dependency. A separate

provider or infrastructure service can exist behind a documented adapter, but

the public application remains responsible for its product contracts and data

rights.

## Durable authority

PostgreSQL is the durable authority for product state, authorization state,

repository metadata, work state, fleet targets, and receipts. A transaction

that does not commit cannot become product truth.

Treat these systems as projections or execution aids:

- LiveView socket assigns and browser state.

- Phoenix PubSub messages.

- BEAM registries, supervisors, tasks, and process mailboxes.

- In-memory caches and `:persistent_term` values.

- Network and deployment status pages.

- Local build and artifact caches.

Immutable artifacts can live in durable object storage, but PostgreSQL records

their identity, digest, lifecycle, and authorized target. Reconcile an

ephemeral projection from durable state after restarts or missed events.

## Trust boundaries

Every route belongs to one authority class. Gate 6 of the hardening plan owns

the exhaustive route ledger and enforcement tests.

| Class | Principal | Examples | Required enforcement |

| --- | --- | --- | --- |

| Public | Anonymous visitor | Home, docs, status, changelog, allowed public code | Read-only behavior, bounded output, and visibility policy |

| Authenticated | Active OpenAgents user | Chat, data rights, computers, issues, projects | Signed session, CSRF protection for browser mutations, and owner or repository scope |

| Operator | Configured active administrator | Administration, promotion, deployment, recording review | Authenticated session plus server-side operator authorization on every action |

| Machine | Paired machine credential | Controller socket, presence, and agent jobs | Hashed or encrypted scoped token, explicit machine ownership, rotation, and revocation |

| Internal service | Configured service identity or signed grant | Inference proxy and build/deployment adapters | Narrow audience and scope, expiry, replay defense, and no browser-held service secret |

| Git | Machine or operator Git credential | `/git` fetch and push | HTTP Basic transport with server-side token verification and repository authorization |

Route placement does not prove authorization. A controller, LiveView mount, or

socket must enforce the class and resource scope at the server boundary. Until

the Gate 6 route audit passes, treat the current router as implementation

evidence rather than a complete authorization policy.

## Provider boundary

Provider adapters implement replaceable server-side behavior. Direct OpenAI

integration is the current default adapter choice for text, embeddings, shadow

programs, and voice. It is not an application-wide contract.

The browser can receive bounded provider-derived events and media negotiation

results, but it must never receive an OpenAI API key, GitHub access token,

forge operator token, machine token, recording key, or internal-service signing

key. Adapters own transport details, timeouts, bounded retries, response

validation, error normalization, and secret redaction. Product contexts own

durable lifecycle and policy.

Tests replace network providers with explicit fakes. A provider outage must

produce a bounded durable failure outcome instead of abandoning an in-flight

turn, work item, or voice session.

## Forge planes

The forge contains two separate planes within the `OpenAgents.Forge`

application namespace:

- The Git plane accepts authenticated Git traffic, stores repositories and

  push receipts, controls visibility, serves public browsing, and mirrors refs.

- The deployment plane promotes an exact pushed SHA, builds immutable

  artifacts, selects a deployment strategy, changes fleet state, rolls back,

  converges restarted nodes, and records receipts.

A push never promotes itself. Git repository availability does not imply that

a build is safe, and a successful build does not imply that a candidate is

live. PostgreSQL transitions connect the planes through an operator-authorized

target.

## Deployment strategies

Direct BEAM load, relup, and rolling replacement solve different problems. The

classifier must select one strategy for the complete candidate and fail closed

when it cannot prove eligibility.

| Strategy | Eligible changes | Required safety proof |

| --- | --- | --- |

| Direct BEAM load | Allowlisted module additions or changes without structural effects | Immutable manifest and digest, fleet prepare/apply/verify transaction, exact binary rollback, and readiness verification |

| Relup | Compatible versioned application changes and explicit process-state migrations | Forward and reverse appup/relup chain, state migration tests, staged install, permanent-release verification, and rollback drill |

| Rolling replacement | ERTS, OTP, NIF, dependency graph, assets, configuration, migrations, module deletion, or unclassified changes | Immutable image digest, node drain, readiness-gated replacement, capacity limits, and last-known-good rollback |

Development code reloading is not a production deployment strategy. Keep every

deployment capability disabled by default until its local proof and isolated

staging drill pass.

## Runtime and staging topology

The accepted target has two isolated staging lanes:

- A web lane proves Phoenix, LiveView, PostgreSQL, authentication, chat, voice,

  data rights, and provider behavior without distributed deployment enabled.

- A three-node distributed lane proves Ra quorum, Git, immutable builds, direct

  loading, relups, rolling replacement, rollback, and boot convergence.

Both lanes use staging-only hosts, credentials, buckets, repositories, service

accounts, and a PostgreSQL instance that does not share a production failure

domain. Production is out of scope until all hardening gates, the complete

staging matrix, failure injection, and the 48-hour soak pass.

## Source control transition

GitHub remains the repository's temporary canonical remote during staging

hardening. The self-hosted forge becomes canonical only through an explicit

cutover after its Git, mirror, artifact, rollback, and recovery gates pass. The

cutover changes contributor instructions and push automation in the same

candidate. After cutover, the forge pushes a read-only GitHub mirror and direct

GitHub pushes become invalid.

Do not describe the cutover as complete while contributor clones and automated

pushes still target GitHub.

## Decision records

- [ADR 0001: Integrate the complete product in the public application](decisions/0001-integrate-the-complete-public-application.md)

- [ADR 0002: Model Sarah as an OpenAgents persona](decisions/0002-model-sarah-as-an-openagents-persona.md)

- [ADR 0003: Keep provider credentials behind server adapters](decisions/0003-keep-provider-credentials-behind-server-adapters.md)

- [ADR 0004: Retain scoped GitHub access tokens in the server vault](decisions/0004-retain-scoped-github-access-tokens.md)

- [ADR 0005: Use Basecoat and one OpenAgents component system](decisions/0005-use-basecoat-and-one-component-system.md)

- [ADR 0006: Isolate web and distributed fleet staging](decisions/0006-isolate-web-and-distributed-fleet-staging.md)

- [ADR 0007: Cut over to forge-canonical source control only after proof](decisions/0007-cut-over-to-forge-canonical-source-control-after-proof.md)

## Superseded narratives

The following documents record earlier plans and measurements. They do not

define the current architecture:

- `docs/chat-inference-plan.md` proposed a private Sarah service boundary that

  the integrated application does not use.

- `docs/sarah-integration-plan.md` records the migration into this repository.

- `docs/2026-08-19-gap-implementation-plan.md` records earlier gap work.

- `docs/beam-hot-deployment-plan.md` contains detailed deployment design, but

  its phase status does not authorize production use.

The [integration hardening and staging readiness plan](2026-08-20-integration-hardening-and-staging-readiness-recommendations.md)

tracks the work required to make this architecture safe and verifiable.

# ADR 0001: Integrate the complete product in the public application

Date: 2026-08-20

Status: Accepted

## Context

Earlier plans divided a public web shell from private Sarah-specific chat,

voice, persona, and provider behavior. The repository now contains and operates

those product capabilities. Maintaining a fictional service split obscures

data ownership, weakens contributor understanding, and leaves public contracts

dependent on undocumented code.

## Decision

Keep the complete OpenAgents product in this AGPL-3.0 repository. The

`openagents.com` application owns the web interface, Sarah behavior,

conversation lifecycle, providers, tools, memory, delegated work, voice,

machines, issues, projects, forge, data rights, and operator surfaces.

Use external services only through explicit infrastructure or provider

adapters. Do not move product policy or Sarah behavior behind an undocumented

private API.

## Consequences

- Contributors can inspect, test, and modify every product contract.

- One application owns data-rights behavior and durable lifecycle recovery.

- Runtime secrets remain private even though orchestration code is public.

- Earlier public-shell and private-Sarah plans are superseded.

# ADR 0002: Model Sarah as an OpenAgents persona

Date: 2026-08-20

Status: Accepted

## Context

Sarah has a distinct identity, voice, behavior contract, persona artifacts,

and evaluation material. Generic runtime infrastructure also inherited Sarah

names during integration. Treating Sarah as either a separate application or a

name for all infrastructure makes ownership unclear.

## Decision

Model Sarah as a persona and behavior package inside the `OpenAgents`

application. Keep Sarah names when identity is part of the contract, including

persona artifact IDs, behavior revisions, evaluations, visible identity, and

voice copy.

Use OpenAgents names for generic supervisors, web helpers, style packs,

runtime paths, build services, test cases, and configuration. Gate 2 performs

that semantic rename and adds an allowlist for intentional references.

## Consequences

- The product can add other personas without duplicating application

  infrastructure.

- Persona-specific history and provenance remain accurate.

- Generic code no longer implies that all OpenAgents behavior belongs to one

  persona.

# ADR 0003: Keep provider credentials behind server adapters

Date: 2026-08-20

Status: Accepted

## Context

Text inference, embeddings, shadow programs, and realtime voice currently use

OpenAI implementations. Product lifecycle code must not depend on one

provider's transport, and browsers must not hold provider credentials.

## Decision

Define provider behavior through server-side adapters. Keep provider request

construction, credentials, transport, timeouts, bounded retries, response

validation, and error normalization behind those adapters. Keep durable turn,

voice, memory, and work policy in provider-independent OpenAgents contexts.

Never send a provider API key or internal-service credential to the browser.

Use explicit fake adapters for tests, and require adapters to redact secrets

from logs, receipts, telemetry, and user-visible errors.

## Consequences

- Direct OpenAI use remains an adapter choice rather than a product boundary.

- The application can replace a provider without rewriting durable lifecycle

  code.

- Browser compromise does not expose server credentials.

- Adapter contracts need conformance, timeout, and failure-path tests.

# ADR 0004: Retain scoped GitHub access tokens in the server vault

Date: 2026-08-20

Status: Accepted; hardening required before staging

## Context

GitHub provides sign-in identity and user-authorized repository access. The

repository already encrypts OAuth access tokens so server-side repository tools

can act with the user's authority. Other documents incorrectly say that the

callback discards the token.

## Decision

Retain the minimum-scoped GitHub access token in the server-side token vault

for features that require GitHub repository access. Encrypt every token with an

operator-managed key, associate it with one active user, and never expose it to

LiveView assigns, browser payloads, logs, receipts, or telemetry.

Keep OpenAgents issue and project data in PostgreSQL; do not use a retained

GitHub token as authority for OpenAgents-owned records. Revoke or delete the

token when the user disconnects GitHub, deletes their data, or loses account

access. Gate 6 must verify scopes, rotation, failure behavior, redaction, and

the disclosures shown to users.

## Consequences

- Authenticated repository tools can use the user's delegated GitHub rights.

- Token retention becomes an explicit data-handling obligation.

- Sign-in identity and repository authorization remain separate decisions.

- Documentation and deletion paths must describe the retained credential.

# ADR 0005: Use Basecoat and one OpenAgents component system

Date: 2026-08-20

Status: Accepted

## Context

The application previously combined DaisyUI, hand-written classes, and

persona-named component wrappers. Conflicting cascade layers made variants

render incorrectly and created multiple ways to build the same control.

## Decision

Use the pinned, vendored Basecoat component CSS as the structural foundation

and one OpenAgents style pack for product identity. Import only the Basecoat

component files that a surface uses. Wrap the system in one Phoenix component

module and use those components before adding surface-specific markup.

Do not add DaisyUI, another component library, remote fonts, icon fonts, or a

second Markdown presentation stack. Rename the generic `SarahUI` module and

style pack during Gate 2 without changing Sarah-specific visual copy.

## Consequences

- Components share one variant, accessibility, token, and interaction model.

- Vendored Basecoat remains separately licensed and must not be patched in

  place.

- The application owns its identity in the style pack rather than in vendored

  source.

- Component and screenshot regression tests can target one catalog.

# ADR 0006: Isolate web and distributed fleet staging

Date: 2026-08-20

Status: Accepted; implementation pending

## Context

Application regressions and distributed deployment failures need different

proof environments. Failure injection, database migration rehearsal, and

rolling replacement are unsafe when staging shares production data,

credentials, infrastructure, or a failure domain.

## Decision

Provision two staging lanes:

- A web lane for Phoenix, LiveView, authentication, chat, voice, data rights,

  PostgreSQL, and provider integration.

- A three-node distributed lane for Ra quorum, Git, builds, direct BEAM load,

  relup, rolling replacement, rollback, and boot convergence.

Give both lanes staging-only hosts, secrets, service accounts, buckets,

repositories, and a PostgreSQL instance that is separate from production.

Disable production promotion until both lanes pass the complete matrix,

failure injection, and a 48-hour soak on one exact candidate.

## Consequences

- Web regressions do not require a distributed deployment experiment.

- Fleet tests can terminate nodes and corrupt disposable artifacts without

  risking production.

- Staging costs more than sharing production infrastructure.

- Gate receipts must name the lane, exact source SHA, artifact and image

  digests, migration version, and staging revision without recording secrets.

# ADR 0007: Cut over to forge-canonical source control after proof

Date: 2026-08-20

Status: Accepted; cutover pending

## Context

The product intends to host its canonical Git repositories on the OpenAgents

forge and keep GitHub as a discoverable read-only mirror. This repository still

uses GitHub as its configured canonical remote during staging hardening. A

documentation-only cutover would split contributor and deployment state.

## Decision

Keep GitHub canonical until the self-hosted Git plane passes authentication,

authorization, durability, mirror, restore, and operational recovery gates.

Perform the cutover as one controlled change that updates contributor

instructions, operator automation, build source, deployment promotion, and

mirror monitoring.

After cutover, accept pushes only through the forge for normal operation. Push

a one-way read-only mirror to GitHub, monitor mirror lag, and treat a direct

GitHub push as an incident. Do not let a mirror push promote a deployment.

## Consequences

- Current contributors keep one accurate remote during hardening.

- The future cutover has explicit prerequisites and rollback evidence.

- GitHub remains available for discovery without becoming a second writable

  authority.

- The application must report canonical-source and mirror state separately.