stack/docs/design/architecture-decisions.md

Architecture Decision Records (ADRs)

ADR-001: API-First with Agent-Agnostic Design

Date: 2025-01-29
Status: Accepted
Deciders: Jason, Jarvis

Context

Mosaic Stack needs to integrate with AI agents (currently ClawdBot, formerly MoltBot). The question is how tightly to couple the platform with the agent layer.

Decision

Mosaic Stack will be API-first and agent-agnostic.

┌─────────────────────────────────────────────────────────────┐
│                        Users                                │
│         (Web UI, Mobile, CLI, API clients)                 │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                    Mosaic Stack                             │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │ Knowledge   │  │ Tasks/Gantt │  │ Agent Orchestration │ │
│  │ Module      │  │ Module      │  │ Module              │ │
│  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘ │
│         │                │                     │            │
│         └────────────────┼─────────────────────┘            │
│                          ▼                                  │
│                    REST/GraphQL APIs                        │
└─────────────────────────┬───────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
    ┌──────────┐    ┌──────────┐    ┌──────────┐
    │ ClawdBot │    │ Other    │    │ Direct   │
    │ Skills   │    │ Agents   │    │ API Use  │
    └──────────┘    └──────────┘    └──────────┘

Implications

1. All functionality exposed via APIs first

   • REST endpoints for CRUD operations
   • GraphQL for complex queries (optional)
   • WebSocket for real-time updates

2. Agent skills are thin wrappers

   • ClawdBot skills (mosaic-skill-*) wrap Mosaic APIs
   • Skills handle: auth, tool definitions, response formatting
   • Business logic lives in Mosaic, not skills

3. Mosaic works standalone

   • Web UI is fully functional without any agent
   • Users can choose to use agents or not
   • Different agents can integrate (ClawdBot, custom, future)

4. Agent layer is swappable

   • Not locked to ClawdBot
   • Could use Claude directly, OpenAI agents, or custom
   • Mosaic is the source of truth

Consequences

Positive:

• Platform independence
• Multiple integration paths
• Clear separation of concerns
• Easier testing (API-level tests)

Negative:

• Extra network hop for agent access
• Need to maintain both API and skill code
• Slightly more initial work

Related Issues

• #22: Brain query API endpoint (API-first ✓)
• #23-26: mosaic-plugin-* → rename to mosaic-skill-* (thin wrappers)

---

Future ADRs will be added to this document.