syndarix/docs/architecture/ARCHITECTURE_OVERVIEW.md

Syndarix Architecture Overview

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

---

Table of Contents

1. Executive Summary
2. System Context
3. High-Level Architecture
4. Core Components
5. Data Architecture
6. Integration Architecture
7. Security Architecture
8. Deployment Architecture
9. Cross-Cutting Concerns
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

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

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

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

---

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	MCP Integration Architecture	Accepted
ADR-002	Real-time Communication	Accepted
ADR-003	Background Task Architecture	Accepted
ADR-004	LLM Provider Abstraction	Accepted
ADR-005	Tech Stack Selection	Accepted
ADR-006	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.