Anima/docs/superpowers/specs/2026-04-12-anima-system-design.md

Anima System Design

Date: 2026-04-12 Status: Draft Author: Till Wegmueller + Claude

Overview

Anima is a strategic work coordination platform for developers who manage projects, AI agents, and collaborative workflows. It is not an IDE — it is the command post layer above, where you assign work, track AI progress, manage discussions (including email threads), and surface documentation.

The system is server-authoritative. The desktop client is a terminal into the command post — it caches for responsiveness but does not own data.

Service Architecture

Services

Service	Role	Runtime
anima-server	Core API + embedded MCP server. Projects, work items, plans, workflows, teams, settings, RBAC. gRPC for desktop client. Forge integration. Seshat's Library client.	Rust binary, always running
anima-mail	Polls Stalwart via JMAP, routes inbound mail to work item threads, sends outbound mail on behalf of work items. Creates/manages mailboxes via Stalwart admin API.	Rust binary, async worker
anima-agent	v1: Single-agent manager. Provisions VM/container, deploys skills, manages agent lifecycle. Interface designed for future multi-provider orchestration.	Rust binary, on-demand
anima-ai	Light AI inference — summaries, gap analysis triggers, thread updates, description generation, mail classification. Stateless, horizontally scalable.	Rust binary, scalable
anima-desktop	Slint desktop client. gRPC to anima-server. Caches for responsiveness, doesn't own data.	Slint/Rust app

External Dependencies

Dependency	Purpose
PostgreSQL	Primary relational store
Stalwart	Mail server (JMAP + admin API + plus-addressing)
Seshat's Library	Document library, vector search (pgvector), blob storage for files/patches/attachments
Forge APIs	GitHub/Gitea/GitLab — PR metadata, issue migration, read-only

Data Flow

Desktop ──gRPC──► anima-server ──SQL──► PostgreSQL
                      │  ╰── MCP (embedded)
                      ├──► Seshat's Library (docs, vectors, blobs)
                      ├──► anima-mail ──JMAP──► Stalwart
                      ├──► anima-ai (light inference, N instances)
                      ├──► anima-agent ──► VM/Container
                      └──► Forge APIs (read-only)

AI in VM ──MCP──► anima-server (scoped token, work item context only)

Domain Model

Entities

Project

• Name, description, status (active/archived)
• Has many Plans, Work Items, Repositories, Mailboxes
• Links to team members with roles via RBAC

Plan

• Belongs to a Project
• Title, description, progress (derived from child work items)
• Has many Work Items
• Phases derived from its Workflow

Work Item

• Belongs to a Project, optionally to a Plan
• Title, description (versioned — every update creates a new revision, revertable), status, priority
• Follows a Workflow (determines phases and required AI skills)
• Has a Discussion Thread (messages, email attachments, AI/Akh contributions)
• Has Patches/PRs (attachments, linked to forge PRs)
• Has Documents (stored in Seshat's Library)
• Has many Agent Sessions (long-running, parallel or sequential)
• Has Capabilities (derived from what the work needs — repo access, API keys, network zones). Agent sessions inherit these.
• Phase tracking within its workflow

Workflow

• Template defining phases (e.g., Analysis → Implementation → Review & Audit)
• Each phase declares required AI Skills
• Ships with defaults, user-customizable
• Future: marketplace for sharing

Discussion Thread

• Belongs to a Work Item
• Ordered messages from: humans, AI (via Akh), email (inbound/outbound)
• AI contributions are promotable to update work item description (creates new revision)
• Email messages carry headers linking back to work item via plus-addressing

Agent Session

• Belongs to a Work Item (many sessions per work item)
• Represents heavy work running in a VM/container
• Status (provisioning, running, paused, completed, failed)
• Has Tasks (sub-units of work within the session)
• Skills deployed, capabilities inherited from work item
• Akh identity configured (persona for thread contributions)
• Long-running once started, persists while work item is open
• Admins can login (SSH) to inspect/debug — audit logged

Akh

• AI persona/identity from the Akh domain
• Agents assume an Akh when writing in discussion threads
• Gives AI contributions a consistent voice and attribution

Repository

• Belongs to a Project
• Forge type (GitHub/Gitea/GitLab), remote URL
• Has Worktrees (checked-out branches, managed by agents in VMs)
• PRs/patches linked to Work Items

Document

• Stored in Seshat's Library (blob + vector embedding)
• Linked to Project and/or Work Item
• Types: markdown, text, patches, attachments
• Searchable by AI via vector queries

Team Member

• User identity, role bindings per project (via RBAC)
• Settings, notification preferences

Mailbox

• Belongs to one or more Projects (no global unattached box)
• A "gather" mailbox is one linked to multiple projects
• Managed via Stalwart admin API
• Plus-address routing rules

Relationships

Project ─┬─► Plans ──► Work Items ─┬─► Discussion Thread (messages, emails, Akh-authored)
         │                         ├─► Patches/PRs
         ├─► Repositories          ├─► Agent Sessions (many, long-running, loginable)
         ├─► Team Members          │     └─► Tasks
         └──►┐                     ├─► Documents (→ Seshat's Library)
     Mailboxes (shared across      ├─► Capabilities (derived, inherited by sessions)
      multiple projects)           ├─► Description Revisions (versioned, revertable)
                                   └─► Workflow (phases, skills)

Akh ──► identity assumed by AI in discussions

gRPC API Design

Public Services (desktop client, embedded MCP)

ProjectService

• ListProjects, GetProject, CreateProject, UpdateProject, ArchiveProject
• ListProjectMembers, AddProjectMember, RemoveProjectMember

PlanService

• ListPlans, GetPlan, CreatePlan, UpdatePlan, DeletePlan

WorkItemService

• ListWorkItems, GetWorkItem, CreateWorkItem, UpdateWorkItem, DeleteWorkItem
• GetDescriptionRevisions, RevertDescription — versioned description management
• ListCapabilities, UpdateCapabilities — derived capabilities attached to work items

WorkflowService

• ListWorkflows, GetWorkflow, CreateWorkflow, UpdateWorkflow, DeleteWorkflow
• Ships with built-in defaults, user workflows stored alongside

ThreadService

• GetThread, PostMessage, PromoteMessage — promote AI message to update work item description (creates new revision)
• StreamThread — server-streaming RPC for live thread updates

AgentSessionService

• ListSessions, GetSession, StartSession, StopSession
• LoginSession — returns connection info for admin SSH/shell access
• ListTasks, GetTask, UpdateTaskStatus
• StreamSessionStatus — server-streaming for live status

RepositoryService

• ListRepositories, AddRepository, RemoveRepository
• ListPatches, AttachPatch — link forge PRs to work items

MailboxService

• ListMailboxes, CreateMailbox, DeleteMailbox
• LinkProjects, UnlinkProjects — manage which projects a mailbox serves

DocumentService

• ListDocuments, GetDocument, UploadDocument, DeleteDocument
• Delegates storage to Seshat's Library

AkhService

• ListAkhs, GetAkh, CreateAkh, UpdateAkh, DeleteAkh

TeamService

• ListUsers, GetUser, CreateUser, UpdateUser, DeleteUser
• Roles and permissions per project via RBAC

DashboardService

• GetDashboard — aggregated view: pending decisions, active sessions, work item status across projects
• StreamDashboardUpdates — live updates

Internal Services (not exposed to desktop)

AnimaAiService (anima-server → anima-ai)

• Summarize, AnalyzeGap, GenerateDescription, ClassifyMail

AgentProviderService (anima-server → anima-agent)

• ProvisionVM, DestroyVM, DeploySkills, GetVMStatus, GetLoginCredentials

API Patterns

• Streaming for anything real-time: threads, agent sessions, dashboard
• Pagination via cursor-based tokens on all List RPCs
• Field masks on Update RPCs for partial updates
• Standard error model with domain-specific error codes

Desktop Client (anima-desktop)

Technology

• Slint for UI rendering (native, cross-platform: macOS, Wayland, X11, Windows)
• Rust for all client logic
• tonic gRPC client for server communication
• Local SQLite cache for responsiveness (read cache, server is source of truth)

Screen Map

Screen	Purpose	Key Data
Dashboard	Morning command view. Pending human decisions, active agent sessions, work item status summaries.	DashboardService
Project List	Grid/list of all projects with status, stats, AI activity indicators.	ProjectService
Project Detail	Plans-centric view. Plans with progress bars, nested work items, phase indicators, repositories, skills.	PlanService, WorkItemService, RepositoryService
Work Item Detail	Full work item view. Versioned description, thread (messages + emails + Akh contributions), patches, phases, capabilities, agent sessions.	WorkItemService, ThreadService, AgentSessionService
Work Item Email Mode	Same work item focused on email thread. Inbound/outbound mail, share buttons.	ThreadService, MailboxService
Library	Document browser. Search, read, manage documents across projects.	DocumentService (→ Seshat's Library)
Workflows	Browse/create/edit workflow templates. Phase editor, skill assignment.	WorkflowService
Settings	Server connection, user preferences, notification settings.	TeamService
Team/People	Team member management, roles per project.	TeamService

Client Architecture

┌─────────────────────────────┐
│         Slint UI Layer       │
│  (.slint files, components)  │
├─────────────────────────────┤
│       View Models (Rust)     │
│  Translate domain → UI state │
├─────────────────────────────┤
│       gRPC Client Layer      │
│  tonic, streaming listeners  │
├─────────────────────────────┤
│       Local Cache (SQLite)   │
│  Read cache, invalidated by  │
│  streaming updates from server│
└─────────────────────────────┘

Caching Strategy

• On startup: fetch current state, populate SQLite cache
• gRPC streams (threads, dashboard, sessions) push updates → invalidate/update cache → UI reacts
• Stale cache is acceptable for offline viewing but all writes go to server
• Cache is disposable — can be wiped and rebuilt from server

Design System

• Headings: Inter
• Body: Geist
• Captions: Funnel Sans
• Color palette: Violet Void (dark theme)
• Roundness: Basic
• Elevation: Sharp depth
• Decorative: Neon streak overlays

Mail Integration (anima-mail)

Inbound Flow

External sender
  → sends to workitem+WI-123@project.anima.example
  → Stalwart receives, stores in project mailbox
  → anima-mail polls via JMAP
  → parses plus-address to extract work item ID
  → calls ThreadService.PostMessage on anima-server (as email-type message)
  → work item thread updated, desktop streams update

Outbound Flow

User clicks "Send" on work item thread (email mode)
  → desktop calls ThreadService.PostMessage (outbound email)
  → anima-server notifies anima-mail
  → anima-mail composes email with:
      - Reply-To: workitem+WI-123@project.anima.example
      - Custom headers: X-Anima-WorkItem, X-Anima-Project
  → sends via JMAP submission to Stalwart
  → recipient replies → inbound flow catches it

Mailbox Management

• anima-mail uses Stalwart's admin API to create/delete mailboxes
• One or more mailboxes per project, linked via MailboxService
• "Gather" mailboxes link to multiple projects — routing uses plus-address to disambiguate
• Compromised addresses get rotated, old mailbox dropped

Spam Handling

• Simple screener on inbound: reject unknown senders on work-item-specific addresses
• Gather mailboxes are more open but can have basic filtering rules
• Compromised addresses get rotated, old mailbox dropped

Mail Classification

• anima-mail calls anima-ai ClassifyMail to route ambiguous inbound mail when plus-addressing isn't present
• Classification always runs on the smallest/cheapest AI model available — it is a simple routing task, not a reasoning task. anima-ai supports model tiers and mail classification always uses the minimal tier.

Agent System (anima-agent)

v1 Scope

Single-agent interaction. One provider (configurable — local Docker, bare-metal hypervisor, or cloud VM). The interface is designed for future multi-provider orchestration but v1 runs one provider.

Lifecycle

Work Item needs heavy work
  → anima-server calls AgentProviderService.ProvisionVM
  → anima-agent provisions VM/container with:
      - Capabilities from work item (repo access, API keys, network rules)
      - AI skills deployed for current workflow phase
      - Akh identity configured (persona for thread contributions)
  → Agent starts working, reports progress via tasks
  → Agent writes to discussion thread as its Akh
  → Session is long-running, persists while work item is open
  → Admin can LoginSession to SSH in and inspect/debug (audit logged)
  → When work completes or is stopped: VM destroyed by default (configurable to keep for debugging)

Capabilities

• Defined on the Work Item, derived from what the work needs
• Examples: access to specific repos, GCP service accounts, k8s API, database credentials, network zones
• anima-agent translates capabilities into VM provisioning config (mounted secrets, firewall rules, IAM bindings)
• No allowlisting needed — the VM only has what the work item declares

Skills Deployment

• Workflow phases declare required AI skills
• anima-agent deploys skills into the VM before the agent starts
• Skills are versioned and stored (future: pulled from marketplace)

Admin Access

• LoginSession returns SSH connection details
• For when AI gets stuck and a human needs to inspect VM state
• Audit logged

MCP Server (embedded in anima-server)

The MCP server exists to give agents running inside VMs access to Anima data relevant to their work item. It is not a general integration point for external tools.

• Scoped tokens: Each agent session gets a token that identifies it. Permissions and scope are stored server-side in the database — looked up on each request.
• No external tool access: The desktop UI is the interface for humans. The MCP is the interface for Anima's own agents only.
• Read-heavy: Agents read work item descriptions, thread history, documents, workflow phase requirements
• Limited writes: Post to thread (as Akh), update task status, flag for human review
• Token lifecycle: Token provisioned when agent session starts, scope stored in DB, revoked on session end

anima-agent provisions VM
  → generates MCP token (identifies agent session)
  → scope stored in DB (work item context, allowed permissions)
  → deploys token into VM alongside skills
  → AI agent inside VM uses MCP to read context and report back
  → token revoked on session end

Future: Multi-Provider Orchestration

The v1 AgentProviderService interface supports future expansion:

• An Agent Orchestrator sits in front of multiple providers
• Providers register capabilities (GCP provider, bare-metal provider, corporate-net provider, Docker provider)
• Orchestrator matches work item capabilities to provider capabilities and dispatches
• Each provider manages its own VM pool
• Scheduler places work on providers based on access requirements (GCP for GCP deployments, corporate-net machine for firewalled k8s API, etc.)

anima-ai Service

Model Tiers

anima-ai supports multiple model tiers. Callers specify the tier, not the model — the service maps tiers to configured models.

Tier	Use Cases	Model Characteristics
Minimal	Mail classification, spam screening, routing	Smallest/cheapest available
Standard	Summaries, description generation, thread digests	Mid-range, good at text
Reasoning	Gap analysis triggers, code review decisions, capability derivation	Stronger reasoning, higher cost

API (internal gRPC, called by anima-server)

• ClassifyMail(mail) → work_item_id, confidence — minimal tier
• Summarize(thread/document) → summary — standard tier
• GenerateDescription(context) → description — standard tier
• AnalyzeGap(plan, implementation_state) → gap_report — reasoning tier
• ShouldReview(work_item, changes) → review_decision — reasoning tier
• DeriveCapabilities(work_item) → capabilities — reasoning tier

Design Principles

• Stateless: no persistent state, reads context from anima-server per request
• Horizontally scalable: run N instances behind a load balancer
• Model-agnostic: tier mapping is configuration, swap models without code changes
• Cost-conscious: always use the cheapest model that can do the job

Authentication & Authorization

Authentication

• Users (humans): Session-based auth against anima-server. Login via credentials (v1), future: OIDC/SSO.
• Desktop client: Authenticates on launch, receives a session token, attaches to all gRPC calls.
• Inter-service: anima-mail, anima-ai, anima-agent authenticate to anima-server with service tokens (pre-shared, rotatable).
• Agent MCP tokens: Tokens identify the agent session only. Scope and permissions are stored server-side in the database, looked up on each request. Revocation is instant.

RBAC System

Full role-based access control:

• Permissions: granular actions (e.g., workitem.create, workitem.read, thread.post, plan.update, agent.login, mailbox.manage)
• Roles: named collections of permissions, stored in database (e.g., Owner, Admin, Member, Viewer)
• Role bindings: user + project + role, stored in database
• Custom roles are a configuration change, not a code change. v1 ships with sensible defaults.

Concept	Storage	Example
Permission	Code-defined enum, referenced in DB	workitem.update, agent.login
Role	DB row, has many permissions	"Admin" → [workitem., plan., agent.login, ...]
Role Binding	DB row: user + project + role	Till → Project Anima → Owner
MCP Token	DB row: token ID → agent session ID	Token abc123 → Session S-42
MCP Scope	DB row: session → work item → allowed permissions	S-42 → WI-17 → [thread.post, workitem.read]

v1 Simplifications

• No OIDC/SSO, just username/password
• Service tokens are static config, rotated manually

Crate & Repository Structure

Workspace Layout

anima/
├── proto/                          # Protobuf definitions
│   └── anima/v1/                   # Versioned API
│       ├── project.proto
│       ├── plan.proto
│       ├── workitem.proto
│       ├── workflow.proto
│       ├── thread.proto
│       ├── agent.proto
│       ├── repository.proto
│       ├── mailbox.proto
│       ├── document.proto
│       ├── akh.proto
│       ├── team.proto
│       ├── dashboard.proto
│       └── ai.proto               # Internal: anima-server → anima-ai
│
├── crates/
│   ├── anima-core/                 # Domain types, RBAC, shared logic
│   ├── anima-db/                   # PostgreSQL migrations, queries (sqlx)
│   ├── anima-proto/                # Generated protobuf code (tonic-build)
│   ├── anima-server/               # Main server binary + embedded MCP
│   ├── anima-mail/                 # Mail worker binary
│   ├── anima-agent/                # Agent manager binary
│   ├── anima-ai/                   # AI inference service binary
│   └── anima-desktop/              # Slint desktop client
│
├── docs/
│   └── superpowers/specs/          # Design specs
│
├── main.pen                        # Penpot design file
├── projectbrief.txt                # Project brief
├── Cargo.toml                      # Workspace root
└── README.md

Crate Dependencies

Crate	Type	Depends On
anima-core	lib	—
anima-proto	lib	anima-core
anima-db	lib	anima-core
anima-server	bin	anima-core, anima-proto, anima-db
anima-mail	bin	anima-proto, anima-core
anima-agent	bin	anima-proto, anima-core
anima-ai	bin	anima-proto, anima-core
anima-desktop	bin	anima-proto, anima-core

Key Rust Dependencies

• tonic / prost — gRPC server & client, protobuf
• sqlx — async PostgreSQL with compile-time query checking
• slint — desktop UI
• tokio — async runtime
• jmap-client or custom — JMAP protocol for Stalwart

Forge Integration

• Read-only forge API integration for GitHub, Gitea, GitLab
• Pull PR/merge request metadata, link to work items
• Issue migration path: import existing issues as work items
• Anima owns work items — no dual issue tracking on forges
• Git operations (clone, commit, push) only happen inside agent VMs (heavy work)
• Patches and documents are attachments stored in Seshat's Library for AI ingestion
• AI reads forge data via MCP when needed during agent sessions

Out of Scope (v1)

• Mobile: The project brief envisions mobile as a "quick response on the go" UI. Not in v1.
• Multi-provider agent orchestration: v1 runs a single agent provider. Multi-provider scheduling is a future expansion.
• Workflow marketplace: v1 ships defaults and allows custom workflows. Marketplace comes later.
• OIDC/SSO: v1 uses username/password. Federation is future work.

Integration Boundaries

Seshat's Library

Seshat's Library is a separate running service with its own API. anima-server communicates with it as an external dependency (like PostgreSQL or Stalwart), not as a linked crate. It provides:

• Blob storage for files, patches, attachments
• Vector embeddings (pgvector) for AI-searchable document library
• Its own API surface that anima-server calls into

Stalwart

anima-mail connects to Stalwart via two interfaces:

• JMAP for reading/sending mail (prefer JMAP EventSource push over polling where available)
• Admin REST API for mailbox lifecycle management

Forge APIs

PR/issue metadata is fetched on-demand when viewing a work item or repository, not continuously polled. Webhooks can be added later for real-time PR status updates if needed.