Module command 

Command/Event/Query Architecture for Headless Core

This module implements the “Headless Core with Multi-Adapter” pattern that enables:

• GUI adapters (Iced, Swift) to control the application through execute/query/subscribe
• AI agents to control the application via MCP server
• CLI tools to automate workflows
• Test harnesses to verify behavior

Architecture

┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│   Iced GUI  │  │  Swift GUI  │  │ MCP Server  │  │     CLI     │
│  (Adapter)  │  │  (Adapter)  │  │  (Adapter)  │  │  (Adapter)  │
└──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       │                │                │                │
       └────────────────┼────────────────┼────────────────┘
                        │                │
                        ▼                ▼
              ┌─────────────────────────────────────┐
              │        CommunitasApp (Core)         │
              │  execute(cmd) / query(q) / sub(s)   │
              └─────────────────────────────────────┘

Key Principles

1. All mutations via Commands - Every state change MUST go through a command. No adapter should directly mutate state.

2. Events record what happened - After a command executes, it produces events that describe what changed. These events can be replayed for debugging/testing.

3. Queries for reads - All state reads go through the Query enum. This enables caching, access control, and consistent responses across adapters.

4. Subscriptions for reactivity - Adapters subscribe to event streams to update their UI when state changes.

Structs

CallResponse

Call response data

CommandError

Error type for command execution

ContactResponse

Contact response data

DiskStatsResponse

Disk stats response data

EntityResponse

Entity response data

FileInfoResponse

File info response data

InviteResponse

Invite response data

KanbanBoardResponse

Kanban board response data

KanbanCardResponse

Kanban card response data

MemberResponse

Member response data

MessageResponse

Message response data

PresenceResponse

Presence response data

QueryError

Error type for query execution

ReactionResponse

SyncStateResponse

Sync state response data

WebsiteResponse

Website response data

Enums

Command

Commands represent all possible mutations to the application state.

DiskTypeArg

Disk type argument for commands (serializable)

Event

Events describe what changed as a result of a command.

Query

Queries represent all possible reads from the application state.

QueryResponse

Response types for queries

Subscription

Subscription types for reactive updates

Type Aliases

CommandResult

Result of executing a command

QueryResult

Result of running a query