# Syndarix

> **Your AI-Powered Software Consulting Agency**
>
> An autonomous platform that orchestrates specialized AI agents to deliver complete software solutions with minimal human intervention.

[![Built on PragmaStack](https://img.shields.io/badge/Built_on-PragmaStack-blue)](https://gitea.pragmazest.com/cardosofelipe/fast-next-template)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

---

## Vision

Syndarix transforms the software development lifecycle by providing a **virtual consulting team** of AI agents that collaboratively plan, design, implement, test, and deliver complete software solutions.

**The Problem:** Even with AI coding assistants, developers spend as much time managing AI as doing the work themselves. Context switching, babysitting, and knowledge fragmentation limit productivity.

**The Solution:** A structured, autonomous agency where specialized AI agents handle different roles (Product Owner, Architect, Engineers, QA, etc.) with proper workflows, reviews, and quality gates.

---

## Key Features

### Multi-Agent Orchestration
- Configurable agent **types** with base model, failover, expertise, and personality
- Spawn multiple **instances** from the same type (e.g., Dave, Ellis, Kate as Software Developers)
- Agent-to-agent communication and collaboration
- Per-instance customization with domain-specific knowledge

### Complete SDLC Support
- **Requirements Discovery** → **Architecture Spike** → **Implementation Planning**
- **Sprint Management** with automated ceremonies
- **Issue Tracking** with Epic/Story/Task hierarchy
- **Git Integration** with proper branch/PR workflows
- **CI/CD Pipelines** with automated testing

### Configurable Autonomy
- From `FULL_CONTROL` (approve everything) to `AUTONOMOUS` (only major milestones)
- Client can intervene at any point
- Transparent progress visibility

### MCP-First Architecture
- All integrations via **Model Context Protocol (MCP)** servers
- Unified Knowledge Base with project/agent scoping
- Git providers (Gitea, GitHub, GitLab) via MCP
- Extensible through custom MCP tools

### Project Complexity Wizard
- **Script** → Minimal process, no repo needed
- **Simple** → Single sprint, basic backlog
- **Medium/Complex** → Full AGILE workflow with multiple sprints

---

## Technology Stack

Built on [PragmaStack](https://gitea.pragmazest.com/cardosofelipe/fast-next-template):

| Component | Technology |
|-----------|------------|
| Backend | FastAPI 0.115+ (Python 3.11+) |
| Frontend | Next.js 16 (React 19) |
| Database | PostgreSQL 15+ with pgvector |
| ORM | SQLAlchemy 2.0 |
| State Management | Zustand + TanStack Query |
| UI | shadcn/ui + Tailwind 4 |
| Auth | JWT dual-token + OAuth 2.0 |
| Testing | pytest + Jest + Playwright |

### Syndarix Extensions
| Component | Technology |
|-----------|------------|
| Task Queue | Celery + Redis |
| Real-time | FastAPI WebSocket / SSE |
| Vector DB | pgvector (PostgreSQL extension) |
| MCP SDK | Anthropic MCP SDK |

---

## Project Status

**Phase:** Architecture & Planning

See [docs/requirements/](./docs/requirements/) for the comprehensive requirements document.

### Current Milestones
- [x] Fork PragmaStack as foundation
- [x] Create requirements document
- [ ] Execute architecture spikes
- [ ] Create ADRs for key decisions
- [ ] Begin MVP implementation

---

## Documentation

- [Requirements Document](./docs/requirements/SYNDARIX_REQUIREMENTS.md)
- [Architecture Decisions](./docs/adrs/) (coming soon)
- [Spike Research](./docs/spikes/) (coming soon)
- [Architecture Overview](./docs/architecture/) (coming soon)

---

## Getting Started

### Prerequisites
- Docker & Docker Compose
- Node.js 20+
- Python 3.11+
- PostgreSQL 15+ (or use Docker)

### Quick Start
```bash
# Clone the repository
git clone https://gitea.pragmazest.com/cardosofelipe/syndarix.git
cd syndarix

# Copy environment template
cp .env.template .env

# Start development environment
docker-compose -f docker-compose.dev.yml up -d

# Run database migrations
make migrate

# Start the development servers
make dev
```

---

## Architecture Overview

```
+====================================================================+
|                         SYNDARIX CORE                               |
+====================================================================+
|  +------------------+  +------------------+  +------------------+   |
|  | Agent Orchestrator|  | Project Manager |  | Workflow Engine  |   |
|  +------------------+  +------------------+  +------------------+   |
+====================================================================+
                              |
                              v
+====================================================================+
|                    MCP ORCHESTRATION LAYER                          |
|  All integrations via unified MCP servers with project scoping      |
+====================================================================+
                              |
     +------------------------+------------------------+
     |                        |                        |
+----v----+  +----v----+  +----v----+  +----v----+  +----v----+
|   LLM   |  |   Git   |  |Knowledge|  |  File   |  |  Code   |
| Providers|  |   MCP   |  |Base MCP |  |Sys. MCP |  |Analysis |
+---------+  +---------+  +---------+  +---------+  +---------+
```

---

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

---

## License

MIT License - see [LICENSE](./LICENSE) for details.

---

## Acknowledgments

- Built on [PragmaStack](https://gitea.pragmazest.com/cardosofelipe/fast-next-template)
- Powered by Claude and the Anthropic API