Changeset 0.9.4 (#54)

ARCHITECTURE.md

@@ -45,6 +45,66 @@ Three Docker images support different deployment scenarios:
 
 5. **Capabilities Resolution**: Model capabilities (vision, tool calling, thinking, context window) are resolved through a priority chain: catalog DB (provider API sync, per-provider authoritative) → heuristic inference (regex patterns on model ID). No static model table — the same model can have different capabilities on different providers. The catalog is populated by auto-fetch on provider creation and manual refresh.
 
+6. **Channels as Execution Context**: Channels are the universal container for conversation state — messages, tool activity, notes, and artifacts all hang off a channel. Today channels are single-user direct chats. The architecture anticipates multi-participant channels (team members, anonymous visitors, AI personas) for workflow execution, without requiring changes to the message tree, tool framework, or streaming infrastructure.
+
+## Workflow Architecture (Future — v0.21.0+)
+
+The platform's existing primitives (teams, personas, channels, tools, notes)
+compose into a workflow engine where the channel is the execution context
+that moves through defined stages.
+
+### Conceptual Model
+
+```
+Team
+ └─ Workflow (team-admin defined)
+      ├─ name, description
+      ├─ entry conditions (public link, team-internal, API trigger)
+      └─ Stages[]
+           ├─ persona_id (which AI drives this stage)
+           ├─ assignment_team_id (who can be assigned)
+           ├─ form_template (structured note schema, optional)
+           └─ transitions[] (conditions → next stage)
+
+Channel (workflow instance)
+ ├─ workflow_id + current_stage
+ ├─ participants[]
+ │    ├─ anonymous visitor (mTLS fingerprint / session token)
+ │    ├─ AI persona (per-stage, from workflow definition)
+ │    └─ assigned team member (claimed or auto-routed)
+ ├─ messages (existing tree structure)
+ ├─ notes (channel-scoped artifacts, intake forms)
+ └─ tool activity (existing execution framework)
+```
+
+### How Existing Primitives Map
+
+| Existing Primitive | Workflow Role |
+|-------------------|---------------|
+| **Persona** (system prompt + model) | Drives a workflow stage — the AI knows what to collect, when to route |
+| **Team** (members + roles) | Owns the workflow definition; members are assignable to channels |
+| **Channel** (messages + tree) | Execution instance of a workflow; full conversation history |
+| **Notes + Tools** | Structured data collection; the persona's system prompt *is* the form definition, the note *is* the filled form |
+| **EventBus + WebSocket** | Real-time notifications for assignment, stage transitions, new messages |
+
+### Design Constraints for Current Development
+
+These invariants keep the workflow path open without building it prematurely:
+
+- **Channels**: Don't assume single-owner. If touching channel queries, keep
+  room for `team_id`, `type` (beyond `direct`), and multi-participant access
+  patterns alongside `user_id`.
+- **Notes**: Currently user-scoped. Future channel-scoped notes (attached to
+  a conversation, not a personal notebook) need a `channel_id` FK option.
+- **Personas**: Already team-scoped. Don't couple to "user picks from dropdown"
+  — a workflow stage references a persona programmatically.
+- **Tool ExecutionContext**: Already carries `UserID` + `ChannelID`. Will need
+  `TeamID` and `WorkflowID` — the struct is easily extended.
+- **Auth**: mTLS anonymous users need identity to participate in channels.
+  Lightest version: a `participants` table that can reference a `user_id` or
+  an opaque session identifier (cert fingerprint). Don't assume every channel
+  participant has a row in `users`.
+
 ## Package Structure
 
 ```