Module command 

Command/Event/Query Architecture for Headless Core

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

• GUI adapters (Iced, Dioxus) 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  │  │ Dioxus 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

CanvasElementResponse

Canvas element response data

CanvasSnapshotResponse

Canvas snapshot response data

ChunkReadResponse

Chunk read response data

ChunkedWriteProgressResponse

Chunked write progress response

CommandError

Error type for command execution

ContactResponse

Contact response data

DiskInfoResponse

Disk info response data

DiskStatsResponse

Disk stats response data

EntityResponse

Entity response data

FileInfoResponse

File info response data

FileMetadataResponse

File metadata response (without content)

FilePreviewResponse

File preview response data

InviteResponse

Invite response data

KanbanBoardResponse

Kanban board response data

KanbanCardResponse

Kanban card response data

KanbanColumnResponse

Kanban column response data

MemberResponse

Member response data

MessageResponse

Message response data

PresenceResponse

Presence response data

QueryError

Error type for query execution

ReactionResponse

ResumableTransferResponse

Resumable transfer info

ResumeVerificationResponse

Resume verification response data

SearchResult

Search result with message and match context.

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

ResumeCapabilityResponse

Resume capability response

Subscription

Subscription types for reactive updates

Type Aliases

AgentId

x0x agent identifier (64-character hex string).

CommandResult

Result of executing a command

QueryResult

Result of running a query