# 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

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```sql
CREATE EXTENSION IF NOT EXISTS vector;
```

This is typically done in an Alembic migration.

### Migrations

```bash
# 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:

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

## Testing

### Backend Tests

```bash
# 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

```bash
# 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

```bash
# 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

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

# List tables
\dt

# Describe table
\d users
```

### Redis

```bash
# 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:
```bash
docker-compose logs db | grep "ready to accept connections"
```

### "Import error" for new dependencies

Rebuild the container:
```bash
docker-compose build --no-cache backend
```

### Migrations out of sync

```bash
# 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](./architecture/ARCHITECTURE.md).