syndarix/docs/adrs/ADR-005-tech-stack-selection.md

ADR-005: Technology Stack Selection

Status: Accepted Date: 2025-12-29 Deciders: Architecture Team

---

Context

Syndarix needs a robust, modern technology stack that can support:

• Multi-agent orchestration with real-time communication
• Full-stack web application with API backend
• Background task processing for long-running operations
• Vector search for RAG (Retrieval-Augmented Generation)
• Multiple external integrations via MCP

The decision was made to build upon PragmaStack as the foundation, extending it with Syndarix-specific components.

Decision Drivers

• Productivity: Rapid development with modern frameworks
• Type Safety: Minimize runtime errors
• Async Performance: Handle concurrent agent operations
• Ecosystem: Rich library support
• Familiarity: Team expertise with selected technologies
• Production-Ready: Proven technologies for production workloads

Decision

Adopt PragmaStack as foundation with Syndarix-specific extensions.

Core Stack (from PragmaStack)

Layer	Technology	Version	Rationale
Backend	FastAPI	0.115+	Async, OpenAPI, type hints
Backend Language	Python	3.11+	Type hints, async/await, ecosystem
Frontend	Next.js	16	React 19, server components, App Router
Frontend Language	TypeScript	5.0+	Type safety, IDE support
Database	PostgreSQL	15+	Robust, extensible, pgvector
ORM	SQLAlchemy	2.0+	Async support, type hints
Validation	Pydantic	2.0+	Data validation, serialization
State Management	Zustand	4.0+	Simple, performant
Data Fetching	TanStack Query	5.0+	Caching, invalidation
UI Components	shadcn/ui	Latest	Accessible, customizable
CSS	Tailwind CSS	4.0+	Utility-first, fast styling
Auth	JWT	-	Dual-token (access + refresh)

Syndarix Extensions

Component	Technology	Version	Purpose
Task Queue	Celery	5.3+	Background job processing
Message Broker	Redis	7.0+	Celery broker, caching, pub/sub
Vector Store	pgvector	Latest	Embeddings for RAG
MCP Framework	FastMCP	2.0+	MCP server development
LLM Abstraction	LiteLLM	Latest	Multi-provider LLM access
Real-time	SSE + WebSocket	-	Event streaming, chat

Testing Stack

Type	Technology	Purpose
Backend Unit	pytest	8.0+
Backend Async	pytest-asyncio	Async test support
Backend Coverage	coverage.py	Code coverage
Frontend Unit	Jest	29+
Frontend Components	React Testing Library	Component testing
E2E	Playwright	1.40+

DevOps Stack

Component	Technology	Purpose
Containerization	Docker	24+
Orchestration	Docker Compose	Local development
CI/CD	Gitea Actions	Automated pipelines
Database Migrations	Alembic	Schema versioning

Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend (Next.js 16)                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   Pages     │  │ Components  │  │   Stores    │              │
│  │ (App Router)│  │ (shadcn/ui) │  │  (Zustand)  │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
└────────────────────────────┬────────────────────────────────────┘
                             │ REST + SSE + WebSocket
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Backend (FastAPI 0.115+)                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │    API      │  │  Services   │  │    CRUD     │              │
│  │   Routes    │  │   Layer     │  │   Layer     │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │ LLM Gateway │  │  MCP Client │  │ Event Bus   │              │
│  │ (LiteLLM)   │  │  Manager    │  │ (Redis)     │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
└────────────────────────────┬────────────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
┌───────────────┐  ┌───────────────┐  ┌───────────────────────────┐
│  PostgreSQL   │  │     Redis     │  │      MCP Servers          │
│  + pgvector   │  │ (Cache/Queue) │  │ (LLM, Git, KB, Issues...) │
└───────────────┘  └───────────────┘  └───────────────────────────┘
                             │
                             ▼
                   ┌───────────────┐
                   │    Celery     │
                   │   Workers     │
                   └───────────────┘

Consequences

Positive

• Proven, production-ready stack
• Strong typing throughout (Python + TypeScript)
• Excellent async performance
• Rich ecosystem for extensions
• Team familiarity reduces learning curve

Negative

• Python GIL limits CPU-bound concurrency (mitigated by Celery)
• Multiple languages (Python + TypeScript) to maintain
• PostgreSQL requires management (vs serverless options)

Neutral

• PragmaStack provides solid foundation but may include unused features
• Stack is opinionated, limiting some technology choices

Version Pinning Strategy

Component	Strategy	Rationale
Python	3.11+ (specific minor)	Stability
Node.js	20 LTS	Long-term support
FastAPI	0.115+	Latest stable
Next.js	16	Current major
PostgreSQL	15+	Required for features

Compliance

This decision aligns with:

• NFR-601: Code quality standards (TypeScript, type hints)
• NFR-603: Docker containerization requirement
• TC-001 through TC-006: Technical constraints

---

This ADR establishes the foundational technology choices for Syndarix.