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:

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

Each app-instance contains the user-facing product:

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

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

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

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

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

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

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

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

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:

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.