forked from cardosofelipe/fast-next-template
feat: Add MCP server stubs, development docs, and Docker updates
- Add MCP server skeleton implementations for all 7 planned servers (llm-gateway, knowledge-base, git, issues, filesystem, code-analysis, cicd) - Add comprehensive DEVELOPMENT.md with setup and usage instructions - Add BACKLOG.md with detailed phase planning - Update docker-compose.dev.yml with Redis and Celery workers - Update CLAUDE.md with Syndarix-specific context Addresses issues #16, #20, #21 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
1656
docs/BACKLOG.md
Normal file
1656
docs/BACKLOG.md
Normal file
File diff suppressed because it is too large
Load Diff
377
docs/DEVELOPMENT.md
Normal file
377
docs/DEVELOPMENT.md
Normal file
@@ -0,0 +1,377 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user