beaver_project/docs/product-discovery/beaver/product-architecture-brief.md

# Beaver Product Architecture Brief

Date: 2026-06-09

Audience: product, engineering, delivery, security, and pilot stakeholders.

## 1. Architecture Summary

Beaver is built as a private-deployable, multi-instance Agent workspace.

At the top level, it has five deployment components:

```text
Browser
  -> auth-portal
  -> authz-service
  -> deploy-control
  -> router-proxy
  -> app-instance
```

Each `app-instance` contains the user-facing product:

```text
app-instance container
  -> Nginx
  -> Next.js frontend
  -> Beaver backend
  -> mounted beaver-home
       -> config
       -> workspace
       -> skills
       -> runtime data
```

The key product architecture choice is instance-level sandboxing. Each user or team can receive a separate app instance with its own config, workspace, files, skills, and runtime data.

## 2. Product-Level System Map

```text
Auth and onboarding
  auth-portal
    -> register/login
    -> model provider onboarding
  authz-service
    -> account and backend identity
  deploy-control
    -> create/configure/remove app-instance
  router-proxy
    -> route instance host to app-instance container

User workspace
  app-instance/frontend
    -> chat workbench
    -> tasks
    -> files
    -> skills
    -> marketplace
    -> MCP/tools
    -> notifications/cron
    -> connectors
    -> settings/status/logs

Agent runtime
  app-instance/backend
    -> interfaces
    -> services
    -> engine
    -> coordinator
    -> tools
    -> skills
    -> memory
    -> integrations
```

## 3. Deployment Components

### Auth Portal

Responsibility:

- User login and registration entry.
- Provider onboarding after registration.
- Handoff into the user app instance.

Product value:

- Gives non-technical users a clean entry point.
- Separates account onboarding from the per-instance app.

Key risk:

- Provider configuration must be understandable and recoverable for non-engineer users.

### AuthZ Service

Responsibility:

- Account and backend identity orchestration.
- Internal token-protected coordination.

Product value:

- Centralizes identity relationships between portal and app backends.

Key risk:

- Misconfigured issuer/internal URL can break new app instances.

### Deploy Control

Responsibility:

- Create, configure, and manage app instances.
- Call `app-instance/create-instance.sh`.
- Write provider config and restart instance when needed.

Product value:

- Makes private instance provisioning repeatable.

Key risk:

- Must not be exposed publicly.
- Needs health checks and lifecycle operations for pilot scale.

### Router Proxy

Responsibility:

- Route hostnames to the correct app instance container.

Product value:

- Lets each instance have a stable public URL.

Key risk:

- Domain, wildcard DNS, HTTPS, and route reload errors can block access.

### App Instance

Responsibility:

- The user-facing Beaver workspace.
- Runs frontend, backend, and Nginx in one container.
- Mounts the instance's `beaver-home` as config and workspace boundary.

Product value:

- Provides practical sandboxing for early private deployments.

Key risk:

- Instance lifecycle, backup, restore, and resource limits need productized operations.

## 4. App Instance Product Modules

### Frontend Modules

| Module | Route | Product Job |
| --- | --- | --- |
| Chat workbench | `/` | Main workspace for conversation, attachments, task cards, and acceptance |
| Tasks | `/tasks`, `/tasks/[taskId]` | Track ordinary and scheduled task lifecycle, timeline, evidence, artifacts |
| Notifications | `/notifications` | Review proactive or scheduled outputs |
| Cron | `/cron` | Manage scheduled jobs |
| Files | `/files` | Browse, upload, preview, download, delete workspace files |
| Skills | `/skills` | Manage published skills, candidates, drafts, safety/eval, review, publish |
| Marketplace | `/marketplace` | Discover and install skills |
| MCP/tools | `/mcp` | Manage tool servers, tool details, test, add, edit, delete |
| Agents | `/agents` | Manage Agent definitions and roles |
| Outlook/connectors | `/outlook`, settings connector panels | Connect external systems |
| Settings/status/logs | `/settings`, `/status`, `/logs` | Configure providers, runtime, channels, health, and debugging |

### Backend Modules

| Module | Responsibility |
| --- | --- |
| `foundation` | Shared config, errors, events, utilities, base models |
| `engine` | Unified Agent runtime used by main Agent and sub-agents |
| `coordinator` | Multi-agent sequence/parallel/DAG execution |
| `tools` | Built-in and MCP tool registration/execution |
| `skills` | Skill loading, resolution, drafts, learning, review, publish |
| `memory` | Long-term memory and run/skill stores |
| `permissions` | Governance and policy surface |
| `services` | Application orchestration, tasks, cron, process projection |
| `interfaces` | Web, CLI, Gateway, channels, MCP servers |
| `integrations` | AuthZ, MCP, external protocols, connector clients |

## 5. Core Product Flows

### Flow A: New User Registration And First Workspace

```text
Browser
  -> auth-portal register
  -> authz-service /portal/register
  -> deploy-control /api/instances/register
  -> create app-instance container
  -> app-instance backend registers user/backend
  -> provider onboarding
  -> deploy-control configures provider
  -> user enters app-instance URL
```

Product requirements:

- Clear success/failure state during provisioning.
- Provider setup can be skipped but instance must explain missing model config later.
- Internal control-plane endpoints stay private.

### Flow B: Chat To Managed Task

```text
User message
  -> chat workbench
  -> backend task router
  -> ordinary chat or task mode
  -> task created
  -> Agent execution
  -> tool calls and artifacts
  -> task timeline
  -> user accepts / asks revision / abandons
```

Product requirements:

- The user must understand when a message became a task.
- The task must be recoverable from chat, task list, and details page.
- Acceptance feedback must influence future learning.

### Flow C: Complex Task With Agent Team

```text
Task request
  -> TaskExecutionPlanner
  -> ExecutionGraph
       -> sequence / parallel / DAG nodes
  -> TaskSkillResolver binds skills or ephemeral guidance
  -> LocalAgentRunner executes nodes
  -> main Agent synthesizes final answer
  -> evidence saved
```

Product requirements:

- Team execution should be visible without overwhelming users.
- Failed subtasks should be diagnosable.
- Final synthesis should cite or summarize subtask evidence.

### Flow D: Skill Learning Loop

```text
Accepted task
  -> skill learning candidate
  -> draft synthesis
  -> safety report
  -> eval report
  -> human review
  -> publish
  -> future skill retrieval
```

Product requirements:

- Only accepted or otherwise high-signal work should become skill candidates.
- Publishing requires review and gates.
- Skill quality must be traceable over versions.

### Flow E: File And Tool Work

```text
User uploads file or Agent needs file/tool
  -> workspace file API or tool registry
  -> Agent tool execution
  -> result returned to context
  -> event/evidence saved
  -> artifact available in task or files
```

Product requirements:

- User-visible file roots must stay simple.
- Tool calls must be recorded.
- Dangerous tools need policy and review.

### Flow F: Scheduled Work And Notifications

```text
User creates scheduled job
  -> cron service stores job
  -> scheduled run triggers task/notification
  -> user reviews output
  -> output can become normal task continuation
```

Product requirements:

- Scheduled outputs need the same acceptance path as manual tasks.
- Failed scheduled runs need alerts and retry/recovery.

### Flow G: External Connectors

```text
Connector setup
  -> channel/connector config
  -> sidecar or external provider
  -> inbound event or outbound action
  -> Beaver task/runtime
  -> response or notification
```

Product requirements:

- External writes need clear user/admin control.
- Connector onboarding must show state, errors, and reconnect steps.
- Multi-instance callback routing must be explicit.

## 6. Governance Boundaries

### Instance Boundary

Each app instance owns:

- `config.json`
- `web_auth_users.json`
- `workspace/`
- skills and runtime state
- provider configuration

Risk:

- Cross-instance leakage would be a critical incident.

### Control Plane Boundary

Public exposure should be limited to:

- Auth portal.
- Router proxy for app instances.

Do not expose:

- `deploy-control`.
- `authz-service`.

### Tool Boundary

Tools are the action surface. Policy should distinguish:

- Read-only tools.
- Workspace-scoped write tools.
- External write tools.
- Destructive tools.
- Credential/permission/payment tools.

### Skill Boundary

Skills guide Agent behavior and tool use. Publishing a bad skill can create repeated bad behavior. Skill publishing therefore needs:

- Candidate quality signal.
- Safety report.
- Eval/replay evidence where possible.
- Human review.
- Version rollback.

### Memory Boundary

Memory creates long-term product value but also trust risk. Productization should include:

- Source.
- Confidence.
- Last used.
- Edit/delete/freeze controls.
- Task evidence showing when memory was used.

## 7. Architecture Maturity

| Area | Maturity | Notes |
| --- | --- | --- |
| Multi-instance deployment | Pilot-ready | Needs lifecycle and health automation |
| Chat workbench | Pilot-ready | UI docs show tested states |
| Task lifecycle | Strong | Core product loop exists |
| Task evidence | Strong foundation | Needs narrative/summary layer |
| Agent team | Functional | Needs product explanation and failure UX |
| Files | Pilot-ready | UI docs show tested workflows |
| Tools/MCP | Functional | Needs policy hardening and admin clarity |
| Skills | Functional | Needs stronger quality gates and reuse metrics |
| Memory | Backend foundation | Needs visible product controls |
| Scheduled work | Basic product capability | Needs stability and clearer run handling |
| Connectors | Mixed maturity | Need pilot-safe connector list |
| Operations | Basic | Needs health console, backup/restore, runbook |

## 8. Architecture Risks

| Risk | Severity | Mitigation |
| --- | --- | --- |
| Control-plane service exposed publicly | Critical | Deployment checks and docs; firewall/proxy validation |
| Instance data leakage | Critical | Path isolation tests, authz tests, MinIO/user-files policy checks |
| Tool side effects without review | High | Tool policy profiles, evidence logs, connector sandbox |
| Provider misconfiguration blocks first use | High | Onboarding checks and settings diagnostics |
| Product surface becomes hard to operate | High | Admin health console and staged pilot scope |
| Memory trust gap | High | Memory control center before broad memory activation |
| Skill quality drift | High | Safety/eval/replay and publish gates |

## 9. Recommended Architecture Roadmap

### Next 30 Days

- Rehearse clean deployment and record missing steps.
- Add pilot health checklist for auth portal, authz, deploy control, router, and app instance.
- Define pilot-safe tools and connectors.
- Add task evidence narrative summary.
- Track accepted task, skill candidate, and skill reuse events.

### Next 90 Days

- Memory Control Center MVP.
- Admin Health Console MVP.
- Instance suspend/resume/backup/restore runbook or tooling.
- Connector sandboxing and side-effect policy.
- Skill replay/eval as part of skill governance.
- Organization/team-level roadmap decision.

## 10. Product Architecture Principle

Beaver should keep its product architecture centered on controlled Agent work:

```text
private workspace
  + task lifecycle
  + tool/file execution
  + evidence
  + acceptance
  + skill/memory reuse
  + operational governance
```

New features should strengthen this loop. Features that do not improve execution, evidence, acceptance, reuse, or governance should be treated as secondary until the pilot motion is proven.