syndarix/docs/DEVELOPMENT.md

Syndarix Development Environment

This guide covers setting up and running the Syndarix development environment.

Prerequisites

• Docker & Docker Compose v2+
• Python 3.12+
• Node.js 20+
• uv (Python package manager)
• Git

Quick Start

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

# Copy environment template
cp .env.example .env

# Start all services
docker-compose -f docker-compose.dev.yml up -d

# View logs
docker-compose logs -f

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                    Docker Compose Development                        │
├─────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐             │
│  │ PostgreSQL│  │   Redis   │  │  Backend │  │ Frontend  │             │
│  │ (pgvector)│  │           │  │ (FastAPI)│  │ (Next.js) │             │
│  │  :5432   │  │   :6379   │  │  :8000   │  │  :3000    │             │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘             │
│                      │                                                │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │                    Celery Workers                                │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │ │
│  │  │ celery-agent│  │  celery-git │  │ celery-sync │              │ │
│  │  │  (4 workers)│  │  (2 workers)│  │  (2 workers)│              │ │
│  │  └─────────────┘  └─────────────┘  └─────────────┘              │ │
│  │  ┌─────────────┐                                                 │ │
│  │  │ celery-beat │  (Scheduler)                                   │ │
│  │  └─────────────┘                                                 │ │
│  └─────────────────────────────────────────────────────────────────┘ │
│                                                                       │
└─────────────────────────────────────────────────────────────────────┘

Services

Core Services

Service	Port	Description
db	5432	PostgreSQL 17 with pgvector extension
redis	6379	Redis 7 for cache, pub/sub, Celery broker
backend	8000	FastAPI backend
frontend	3000	Next.js frontend

Celery Workers

Worker	Queue	Concurrency	Purpose
celery-agent	agent	4	Agent execution tasks
celery-git	git	2	Git operations
celery-sync	sync	2	Issue synchronization
celery-beat	-	1	Scheduled task scheduler

Environment Variables

Copy .env.example to .env and configure:

# Database
POSTGRES_USER=syndarix
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=syndarix
DATABASE_URL=postgresql://syndarix:your_secure_password@db:5432/syndarix

# Redis
REDIS_URL=redis://redis:6379/0

# Security
SECRET_KEY=your_32_character_secret_key_here

# Frontend
NEXT_PUBLIC_API_URL=http://localhost:8000

# CORS
BACKEND_CORS_ORIGINS=["http://localhost:3000"]

Development Commands

Backend

# Enter backend directory
cd backend

# Install dependencies
uv sync

# Run tests
IS_TEST=True uv run pytest

# Run with coverage
IS_TEST=True uv run pytest --cov=app --cov-report=html

# Run linting
uv run ruff check .

# Run type checking
uv run mypy app

# Generate migration
python migrate.py auto "description"

# Apply migrations
python migrate.py upgrade

Frontend

# Enter frontend directory
cd frontend

# Install dependencies
npm install

# Run development server
npm run dev

# Run tests
npm test

# Run E2E tests
npm run test:e2e

# Generate API client from backend OpenAPI spec
npm run generate:api

# Type check
npm run type-check

Docker Compose

# Start all services
docker-compose -f docker-compose.dev.yml up -d

# Start specific services
docker-compose -f docker-compose.dev.yml up -d db redis backend

# View logs
docker-compose -f docker-compose.dev.yml logs -f backend

# Rebuild after Dockerfile changes
docker-compose -f docker-compose.dev.yml build --no-cache backend

# Stop all services
docker-compose -f docker-compose.dev.yml down

# Stop and remove volumes (clean slate)
docker-compose -f docker-compose.dev.yml down -v

Celery

# View Celery worker status
docker-compose exec celery-agent celery -A app.celery_app inspect active

# View scheduled tasks
docker-compose exec celery-beat celery -A app.celery_app inspect scheduled

# Purge all queues (caution!)
docker-compose exec celery-agent celery -A app.celery_app purge

Database Setup

Enable pgvector Extension

The pgvector extension is automatically available with the pgvector/pgvector:pg17 image.

To enable it in your database:

CREATE EXTENSION IF NOT EXISTS vector;

This is typically done in an Alembic migration.

Migrations

# Check current migration status
python migrate.py current

# Generate new migration
python migrate.py auto "Add agent tables"

# Apply migrations
python migrate.py upgrade

# Rollback one migration
python migrate.py downgrade -1

MCP Servers (Phase 2+)

MCP servers are located in mcp-servers/. Each server is a FastMCP application.

Server	Priority	Status
llm-gateway	1	Skeleton
knowledge-base	2	Skeleton
git	3	Skeleton
issues	4	Skeleton
filesystem	5	Skeleton
code-analysis	6	Skeleton
cicd	7	Skeleton

To run an MCP server locally:

cd mcp-servers/llm-gateway
uv sync
uv run python server.py

Testing

Backend Tests

# Unit tests (uses SQLite in-memory)
IS_TEST=True uv run pytest

# E2E tests (requires Docker)
make test-e2e

# Run specific test file
IS_TEST=True uv run pytest tests/api/test_auth.py

# Run with verbose output
IS_TEST=True uv run pytest -v

Frontend Tests

# Unit tests
npm test

# E2E tests (Playwright)
npm run test:e2e

# E2E with UI
npm run test:e2e:ui

# E2E debug mode
npm run test:e2e:debug

Debugging

Backend

# View backend logs
docker-compose logs -f backend

# Access container shell
docker-compose exec backend bash

# Run Python REPL with app context
docker-compose exec backend python
>>> from app.core.config import settings
>>> print(settings.PROJECT_NAME)

Database

# Connect to PostgreSQL
docker-compose exec db psql -U syndarix -d syndarix

# List tables
\dt

# Describe table
\d users

Redis

# Connect to Redis CLI
docker-compose exec redis redis-cli

# List all keys
KEYS *

# Check pub/sub channels
PUBSUB CHANNELS *

Common Issues

"Port already in use"

Stop conflicting services or change ports in docker-compose.dev.yml.

"Database connection refused"

Wait for PostgreSQL healthcheck to pass:

docker-compose logs db | grep "ready to accept connections"

"Import error" for new dependencies

Rebuild the container:

docker-compose build --no-cache backend

Migrations out of sync

# Check current state
python migrate.py current

# If needed, stamp current revision
python migrate.py stamp head

IDE Setup

VS Code

Recommended extensions:

• Python
• Pylance
• Ruff
• ESLint
• Prettier
• Docker
• GitLens

PyCharm

1. Set Python interpreter to uv's .venv
2. Enable Ruff integration
3. Configure pytest as test runner

Next Steps

1. Set up your .env file with appropriate values
2. Start the development environment: docker-compose -f docker-compose.dev.yml up -d
3. Run migrations: cd backend && python migrate.py upgrade
4. Access the frontend at http://localhost:3000
5. Access the API docs at http://localhost:8000/docs

For architecture details, see ARCHITECTURE.md.