# 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._