# Syndarix Architecture Overview

**Version:** 1.0
**Date:** 2025-12-29
**Status:** Draft

---

## Table of Contents

1. [Executive Summary](#1-executive-summary)
2. [System Context](#2-system-context)
3. [High-Level Architecture](#3-high-level-architecture)
4. [Core Components](#4-core-components)
5. [Data Architecture](#5-data-architecture)
6. [Integration Architecture](#6-integration-architecture)
7. [Security Architecture](#7-security-architecture)
8. [Deployment Architecture](#8-deployment-architecture)
9. [Cross-Cutting Concerns](#9-cross-cutting-concerns)
10. [Architecture Decisions](#10-architecture-decisions)

---

## 1. Executive Summary

Syndarix is an AI-powered software consulting agency platform that orchestrates specialized AI agents to deliver complete software solutions autonomously. This document describes the technical architecture that enables:

- **Multi-Agent Orchestration:** 10 specialized agent roles collaborating on projects
- **MCP-First Integration:** All external tools via Model Context Protocol
- **Real-time Visibility:** SSE-based event streaming for progress tracking
- **Autonomous Workflows:** Configurable autonomy levels from full control to autonomous
- **Full Artifact Delivery:** Code, documentation, tests, and ADRs

### Architecture Principles

1. **MCP-First:** All integrations through unified MCP servers
2. **Event-Driven:** Async communication via Redis Pub/Sub
3. **Type-Safe:** Full typing in Python and TypeScript
4. **Stateless Services:** Horizontal scaling through stateless design
5. **Explicit Scoping:** All operations scoped to project/agent

---

## 2. System Context

### Context Diagram

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              EXTERNAL ACTORS                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│  │   Client    │    │   Admin     │    │ LLM APIs    │    │ Git Hosts   │  │
│  │   (Human)   │    │   (Human)   │    │ (Anthropic) │    │  (Gitea)    │  │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘    └──────┬──────┘  │
│         │                  │                  │                  │          │
└─────────│──────────────────│──────────────────│──────────────────│──────────┘
          │                  │                  │                  │
          │ Web UI           │ Admin UI         │ API              │ API
          │ SSE              │                  │                  │
          ▼                  ▼                  ▼                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│                              SYNDARIX PLATFORM                              │
│                                                                             │
│   ┌─────────────────────────────────────────────────────────────────────┐   │
│   │                         Agent Orchestration                          │   │
│   │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐            │   │
│   │  │   PO   │ │   PM   │ │  Arch  │ │  Eng   │ │   QA   │  ...       │   │
│   │  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘            │   │
│   └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
          │                  │                  │                  │
          │ Storage          │ Events           │ Tasks            │
          ▼                  ▼                  ▼                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              INFRASTRUCTURE                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │
│  │ PostgreSQL  │    │    Redis    │    │   Celery    │    │MCP Servers  │  │
│  │ + pgvector  │    │   Pub/Sub   │    │   Workers   │    │ (7 types)   │  │
│  └─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Key Actors

| Actor | Type | Interaction |
|-------|------|-------------|
| Client | Human | Web UI, approvals, feedback |
| Admin | Human | Configuration, monitoring |
| LLM Providers | External | Claude, GPT-4, local models |
| Git Hosts | External | Gitea, GitHub, GitLab |
| CI/CD Systems | External | Gitea Actions, etc. |

---

## 3. High-Level Architecture

### Layered Architecture

```
┌───────────────────────────────────────────────────────────────────┐
│                      PRESENTATION LAYER                           │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                    Next.js 16 Frontend                       │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │  │
│  │  │Dashboard │  │ Projects │  │  Agents  │  │  Issues  │    │  │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │  │
│  └─────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────┘
                                │
                                │ REST + SSE + WebSocket
                                ▼
┌───────────────────────────────────────────────────────────────────┐
│                       APPLICATION LAYER                           │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                    FastAPI Backend                           │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │  │
│  │  │   Auth   │  │   API    │  │ Services │  │  Events  │    │  │
│  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │  │
│  └─────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌───────────────────────────────────────────────────────────────────┐
│                       ORCHESTRATION LAYER                         │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐   │  │
│  │  │    Agent      │  │   Workflow    │  │    Project    │   │  │
│  │  │ Orchestrator  │  │    Engine     │  │   Manager     │   │  │
│  │  └───────────────┘  └───────────────┘  └───────────────┘   │  │
│  └─────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌───────────────────────────────────────────────────────────────────┐
│                      INTEGRATION LAYER                            │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                    MCP Client Manager                        │  │
│  │  Connects to: LLM, Git, KB, Issues, FS, Code, CI/CD MCPs    │  │
│  └─────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌───────────────────────────────────────────────────────────────────┐
│                       DATA LAYER                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐            │
│  │  PostgreSQL  │  │    Redis     │  │  File Store  │            │
│  │  + pgvector  │  │              │  │              │            │
│  └──────────────┘  └──────────────┘  └──────────────┘            │
└───────────────────────────────────────────────────────────────────┘
```

---

## 4. Core Components

### 4.1 Agent Orchestrator

**Purpose:** Manages agent lifecycle, spawning, communication, and coordination.

**Responsibilities:**
- Spawn agent instances from type definitions
- Route messages between agents
- Manage agent context and memory
- Handle agent failover
- Track resource usage

**Key Patterns:**
- Type-Instance pattern (types define templates, instances are runtime)
- Message routing with priority queues
- Context compression for long-running agents

See: [ADR-006: Agent Orchestration](../adrs/ADR-006-agent-orchestration.md)

### 4.2 Workflow Engine

**Purpose:** Orchestrates multi-step workflows and agent collaboration.

**Responsibilities:**
- Execute workflow templates (requirements discovery, sprint, etc.)
- Track workflow state and progress
- Handle branching and conditions
- Manage approval gates

**Workflow Types:**
- Requirements Discovery
- Architecture Spike
- Sprint Planning
- Implementation
- Sprint Demo

### 4.3 Project Manager (Component)

**Purpose:** Manages project lifecycle, configuration, and state.

**Responsibilities:**
- Create and configure projects
- Manage complexity levels
- Track project status
- Generate reports

### 4.4 LLM Gateway

**Purpose:** Unified LLM access with failover and cost tracking.

**Implementation:** LiteLLM-based router with:
- Multiple model groups (high-reasoning, fast-response)
- Automatic failover chain
- Per-agent token tracking
- Redis-backed caching

See: [ADR-004: LLM Provider Abstraction](../adrs/ADR-004-llm-provider-abstraction.md)

### 4.5 MCP Client Manager

**Purpose:** Connects to all MCP servers and routes tool calls.

**Implementation:**
- SSE connections to 7 MCP server types
- Automatic reconnection
- Request/response correlation
- Scoped tool calls with project_id/agent_id

See: [ADR-001: MCP Integration Architecture](../adrs/ADR-001-mcp-integration-architecture.md)

### 4.6 Event Bus

**Purpose:** Real-time event distribution using Redis Pub/Sub.

**Channels:**
- `project:{project_id}` - Project-scoped events
- `agent:{agent_id}` - Agent-specific events
- `system` - System-wide announcements

See: [ADR-002: Real-time Communication](../adrs/ADR-002-realtime-communication.md)

---

## 5. Data Architecture

### 5.1 Entity Model

```
┌─────────────┐       ┌─────────────┐       ┌─────────────┐
│    User     │───1:N─│   Project   │───1:N─│   Sprint    │
└─────────────┘       └─────────────┘       └─────────────┘
                             │ 1:N                │ 1:N
                             │                    │
                      ┌──────┴──────┐      ┌──────┴──────┐
                      │             │      │             │
               ┌──────┴──────┐ ┌────┴────┐ │       ┌─────┴─────┐
               │ AgentInstance│ │Repository│ │       │   Issue   │
               └─────────────┘ └─────────┘ │       └───────────┘
                      │               │     │              │
                      │ 1:N           │ 1:N │              │ 1:N
               ┌──────┴──────┐ ┌──────┴────┐│       ┌──────┴──────┐
               │   Message   │ │PullRequest│└───────│IssueComment │
               └─────────────┘ └───────────┘        └─────────────┘
```

### 5.2 Key Entities

| Entity | Purpose | Key Fields |
|--------|---------|------------|
| User | Human users | email, auth |
| Project | Work containers | name, complexity, autonomy_level |
| AgentType | Agent templates | base_model, expertise, system_prompt |
| AgentInstance | Running agents | name, project_id, context |
| Issue | Work items | type, status, external_tracker_fields |
| Sprint | Time-boxed iterations | goal, velocity |
| Repository | Git repos | provider, clone_url |
| KnowledgeDocument | RAG documents | content, embedding_id |

### 5.3 Vector Storage

**pgvector** extension for:
- Document embeddings (RAG)
- Semantic search across knowledge base
- Agent context similarity

---

## 6. Integration Architecture

### 6.1 MCP Server Registry

| Server | Port | Purpose | Priority Providers |
|--------|------|---------|-------------------|
| LLM Gateway | 9001 | LLM routing | Anthropic, OpenAI, Ollama |
| Git MCP | 9002 | Git operations | Gitea, GitHub, GitLab |
| Knowledge Base | 9003 | RAG search | pgvector |
| Issues MCP | 9004 | Issue tracking | Gitea, GitHub, GitLab |
| File System | 9005 | Workspace files | Local FS |
| Code Analysis | 9006 | Static analysis | Ruff, ESLint |
| CI/CD MCP | 9007 | Pipelines | Gitea Actions |

### 6.2 External Integration Diagram

```
┌─────────────────────────────────────────────────────────────────┐
│                        Syndarix Backend                          │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    MCP Client Manager                     │   │
│  │                                                          │   │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │   │
│  │  │  LLM   │ │  Git   │ │   KB   │ │ Issues │ │ CI/CD  │ │   │
│  │  │ Client │ │ Client │ │ Client │ │ Client │ │ Client │ │   │
│  │  └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘ │   │
│  └──────│──────────│──────────│──────────│──────────│──────┘   │
└─────────│──────────│──────────│──────────│──────────│──────────┘
          │          │          │          │          │
          │ SSE      │ SSE      │ SSE      │ SSE      │ SSE
          ▼          ▼          ▼          ▼          ▼
     ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
     │  LLM   │ │  Git   │ │   KB   │ │ Issues │ │ CI/CD  │
     │  MCP   │ │  MCP   │ │  MCP   │ │  MCP   │ │  MCP   │
     │ Server │ │ Server │ │ Server │ │ Server │ │ Server │
     └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘
         │          │          │          │          │
         ▼          ▼          ▼          ▼          ▼
    ┌─────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
    │Anthropic│ │ Gitea  │ │pgvector│ │ Gitea  │ │ Gitea  │
    │ OpenAI  │ │ GitHub │ │        │ │ Issues │ │Actions │
    │ Ollama  │ │ GitLab │ │        │ │        │ │        │
    └─────────┘ └────────┘ └────────┘ └────────┘ └────────┘
```

---

## 7. Security Architecture

### 7.1 Authentication

- **JWT Dual-Token:** Access token (15 min) + Refresh token (7 days)
- **OAuth 2.0 Provider:** For MCP client authentication
- **Service Tokens:** Internal service-to-service auth

### 7.2 Authorization

- **RBAC:** Role-based access control
- **Project Scoping:** All operations scoped to projects
- **Agent Permissions:** Agents operate within project scope

### 7.3 Data Protection

- **TLS 1.3:** All external communications
- **Encryption at Rest:** Database encryption
- **Secrets Management:** Environment-based, never in code

---

## 8. Deployment Architecture

### 8.1 Container Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        Docker Compose                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │ Frontend │  │ Backend  │  │ Workers  │  │  Flower  │        │
│  │ (Next.js)│  │ (FastAPI)│  │ (Celery) │  │(Monitor) │        │
│  │  :3000   │  │  :8000   │  │          │  │  :5555   │        │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐        │
│  │ LLM MCP  │  │ Git MCP  │  │  KB MCP  │  │Issues MCP│        │
│  │  :9001   │  │  :9002   │  │  :9003   │  │  :9004   │        │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘        │
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                      │
│  │  FS MCP  │  │ Code MCP │  │CI/CD MCP │                      │
│  │  :9005   │  │  :9006   │  │  :9007   │                      │
│  └──────────┘  └──────────┘  └──────────┘                      │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                      Infrastructure                       │   │
│  │  ┌──────────┐  ┌──────────┐                              │   │
│  │  │PostgreSQL│  │  Redis   │                              │   │
│  │  │  :5432   │  │  :6379   │                              │   │
│  │  └──────────┘  └──────────┘                              │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

### 8.2 Scaling Strategy

| Component | Scaling | Strategy |
|-----------|---------|----------|
| Frontend | Horizontal | Stateless, behind LB |
| Backend | Horizontal | Stateless, behind LB |
| Celery Workers | Horizontal | Queue-based routing |
| MCP Servers | Horizontal | Stateless singletons |
| PostgreSQL | Vertical + Read Replicas | Primary/replica |
| Redis | Cluster | Sentinel or Cluster mode |

---

## 9. Cross-Cutting Concerns

### 9.1 Logging

- **Format:** Structured JSON
- **Correlation:** Request IDs across services
- **Levels:** DEBUG, INFO, WARNING, ERROR, CRITICAL

### 9.2 Monitoring

- **Metrics:** Prometheus-compatible export
- **Traces:** OpenTelemetry (future)
- **Dashboards:** Grafana (optional)

### 9.3 Error Handling

- **Agent Errors:** Logged, published via SSE
- **Task Failures:** Celery retry with backoff
- **Integration Errors:** Circuit breaker pattern

---

## 10. Architecture Decisions

### Summary of ADRs

| ADR | Title | Status |
|-----|-------|--------|
| [ADR-001](../adrs/ADR-001-mcp-integration-architecture.md) | MCP Integration Architecture | Accepted |
| [ADR-002](../adrs/ADR-002-realtime-communication.md) | Real-time Communication | Accepted |
| [ADR-003](../adrs/ADR-003-background-task-architecture.md) | Background Task Architecture | Accepted |
| [ADR-004](../adrs/ADR-004-llm-provider-abstraction.md) | LLM Provider Abstraction | Accepted |
| [ADR-005](../adrs/ADR-005-tech-stack-selection.md) | Tech Stack Selection | Accepted |
| [ADR-006](../adrs/ADR-006-agent-orchestration.md) | Agent Orchestration | Accepted |

### Key Decisions Summary

1. **Unified Singleton MCP Servers** with project/agent scoping
2. **SSE for real-time events**, WebSocket only for chat
3. **Celery + Redis** for background tasks
4. **LiteLLM** for unified LLM abstraction with failover
5. **PragmaStack** as foundation with Syndarix extensions
6. **Type-Instance pattern** for agent orchestration

---

## Appendix A: Technology Stack Quick Reference

| Layer | Technology |
|-------|------------|
| Frontend | Next.js 16, React 19, TypeScript, Tailwind, shadcn/ui |
| Backend | FastAPI, Python 3.11+, SQLAlchemy 2.0, Pydantic 2.0 |
| Database | PostgreSQL 15+ with pgvector |
| Cache/Queue | Redis 7.0+ |
| Task Queue | Celery 5.3+ |
| MCP | FastMCP 2.0 |
| LLM | LiteLLM (Claude, GPT-4, Ollama) |
| Testing | pytest, Jest, Playwright |
| Container | Docker, Docker Compose |

---

## Appendix B: Port Reference

| Service | Port |
|---------|------|
| Frontend | 3000 |
| Backend | 8000 |
| PostgreSQL | 5432 |
| Redis | 6379 |
| Flower | 5555 |
| LLM MCP | 9001 |
| Git MCP | 9002 |
| KB MCP | 9003 |
| Issues MCP | 9004 |
| FS MCP | 9005 |
| Code MCP | 9006 |
| CI/CD MCP | 9007 |

---

*This document provides the comprehensive architecture overview for Syndarix. For detailed decisions, see the individual ADRs.*
