forked from cardosofelipe/fast-next-template
Felipe Cardoso
6e3cdebbfb
- Added the following ADRs to `docs/adrs/` directory: - ADR-001: MCP Integration Architecture - ADR-002: Real-time Communication Architecture - ADR-003: Background Task Architecture - ADR-004: LLM Provider Abstraction - ADR-005: Technology Stack Selection - Each ADR details the context, decision drivers, considered options, final decisions, and implementation plans. - Documentation aligns technical choices with architecture principles and system requirements for Syndarix.
157 lines
7.8 KiB
Markdown
157 lines
7.8 KiB
Markdown
# 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+ | Python testing |
|
|
| **Backend Async** | pytest-asyncio | Async test support |
|
|
| **Backend Coverage** | coverage.py | Code coverage |
|
|
| **Frontend Unit** | Jest | 29+ | React testing |
|
|
| **Frontend Components** | React Testing Library | Component testing |
|
|
| **E2E** | Playwright | 1.40+ | Browser automation |
|
|
|
|
### DevOps Stack
|
|
|
|
| Component | Technology | Purpose |
|
|
|-----------|------------|---------|
|
|
| **Containerization** | Docker | 24+ | Application packaging |
|
|
| **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.*
|