Development Guide - Serelo

Last Updated: October 13, 2025 Audience: Developers and AI Assistants

🏗️ Local Development Architecture

Overview

Serelo uses a hybrid development environment:

Frontend: Runs natively on host machine with hot reload
Backend: Runs in Docker containers with all dependencies

This setup provides the best developer experience:

✅ Fast frontend hot reload (no Docker overhead)
✅ Isolated backend services (consistent environment)
✅ Easy dependency management (no local Python setup needed)

🚀 Quick Start

1. Start Backend Services (Docker)

# From project root
cd d:\Workspace\Artemis-Innovations\serelo
docker compose up -d --build

Services Started:

serelo_api - FastAPI backend (port 8000)
serelo_mongodb - MongoDB database (port 27017)
serelo_redis - Redis cache (port 6379)
serelo_minio - MinIO S3-compatible storage (port 9000)
serelo_celery_worker - Celery task worker
serelo_celery_beat - Celery scheduler

Verify Backend:

# Check all containers are running
docker ps

# Check backend health
curl http://localhost:8000/health

2. Start Frontend Development Server (Host)

# From project root
cd d:\Workspace\Artemis-Innovations\serelo\frontend
npm run dev

Access Application:

🧪 Testing Strategy

Critical Rule for AI Assistants

⚠️ NEVER run backend tests directly on the host machine!

# ❌ WRONG - Will fail due to missing services
python -m pytest tests/test_auth.py

# ✅ CORRECT - Run tests inside Docker container
docker exec serelo_api python -m pytest tests/test_auth.py -v

Frontend Tests (Run on Host)

Frontend tests run natively and MUST ALWAYS PASS before committing:

cd frontend

# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run tests with coverage
npm test -- --coverage

# Run specific test file
npm test -- src/components/Button.test.tsx

Pre-commit Requirement: All frontend tests must pass locally.

Backend Tests (Run in Docker)

Backend tests require MongoDB, Redis, and other services, so they MUST run inside Docker:

# Run all tests
docker exec serelo_api python -m pytest tests/ -v

# Run specific test file
docker exec serelo_api python -m pytest tests/test_auth.py -v

# Run specific test
docker exec serelo_api python -m pytest tests/test_auth.py::test_register_success -v

# Run with detailed output
docker exec serelo_api python -m pytest tests/test_auth.py -v -s

# Run with short traceback
docker exec serelo_api python -m pytest tests/ -v --tb=short

# Run and stop on first failure
docker exec serelo_api python -m pytest tests/ -v -x

# Run only failed tests from last run
docker exec serelo_api python -m pytest tests/ -v --lf

Test Collection Check:

# List all tests without running
docker exec serelo_api python -m pytest tests/ --collect-only

Why Docker for Backend Tests?

Database Dependency: Tests need MongoDB running
Redis Dependency: Caching and session tests need Redis
S3 Dependency: File upload tests need MinIO
Celery Dependency: Background task tests need Celery worker
Consistent Environment: Same Python version, packages, and configuration as production
Network Isolation: Tests use Docker network to communicate between services

Test Configuration

Test Database: serelo_test_db (separate from dev database serelo_db) Test Environment: Set via TESTING=1 environment variable in conftest.py Rate Limiting: Disabled in tests via TESTING=1

🔧 Common Development Tasks

Rebuild Backend After Code Changes

# Stop containers
docker compose down

# Rebuild and restart (includes latest code changes)
docker compose up -d --build

When to Rebuild:

✅ After changing Python dependencies (requirements.txt)
✅ After changing backend code that's not in mounted volume
✅ After changing conftest.py or test fixtures
✅ After changing Docker configuration
❌ Not needed for changes in mounted volumes (backend/app/, tests/)

View Backend Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f api

# Last 100 lines
docker compose logs --tail=100 api

Access Backend Shell

# Python shell in backend container
docker exec -it serelo_api python

# Bash shell in backend container
docker exec -it serelo_api bash

Database Operations

# Access MongoDB shell
docker exec -it serelo_mongodb mongosh

# List databases
docker exec -it serelo_mongodb mongosh --eval "show dbs"

# Drop test database
docker exec -it serelo_mongodb mongosh serelo_test_db --eval "db.dropDatabase()"

Clear All Data (Fresh Start)

# Stop and remove containers, volumes, and networks
docker compose down -v

# Rebuild from scratch
docker compose up -d --build

📁 Project Structure

Key Directories

serelo/
├── frontend/                 # React/TypeScript frontend (runs on host)
│   ├── src/
│   │   ├── components/       # React components
│   │   ├── pages/            # Page components
│   │   ├── services/         # API client, utilities
│   │   ├── hooks/            # Custom React hooks
│   │   └── utils/            # Helper functions
│   ├── tests/                # Frontend tests
│   └── package.json          # npm dependencies
│
├── backend/                  # FastAPI backend (runs in Docker)
│   ├── app/
│   │   ├── api/              # API endpoints
│   │   ├── core/             # Core utilities, config
│   │   ├── db/               # Database connections
│   │   ├── models/           # Data models
│   │   ├── schemas/          # Pydantic schemas
│   │   └── tasks/            # Celery tasks
│   ├── requirements.txt      # Python dependencies
│   └── Dockerfile
│
├── tests/                    # Backend tests (mounted in Docker)
│   ├── conftest.py           # Pytest fixtures and configuration
│   ├── test_auth.py
│   ├── test_projects.py
│   └── ...
│
├── docker-compose.yml        # Docker services configuration
└── pytest.ini                # Pytest configuration

Mounted Volumes

Docker mounts these directories for hot reload:

backend/app/ → /app/app/ (backend code)
tests/ → /app/tests/ (test files)

Changes to these directories are immediately available in Docker without rebuild.

🐛 Debugging

Frontend Debugging

Browser DevTools: Chrome/Firefox DevTools (F12)
React DevTools: Install browser extension
Console Logs: Check browser console for errors
Network Tab: Inspect API calls and responses

Backend Debugging

# View API logs in real-time
docker compose logs -f api

# Check specific endpoint
curl http://localhost:8000/api/v1/auth/me -H "Authorization: Bearer <token>"

# Access API documentation
# Open: http://localhost:8000/docs

Test Debugging

# Run test with print statements visible
docker exec serelo_api python -m pytest tests/test_auth.py -v -s

# Run test with full traceback
docker exec serelo_api python -m pytest tests/test_auth.py -v --tb=long

# Run test with PDB debugger (drops into Python debugger on failure)
docker exec -it serelo_api python -m pytest tests/test_auth.py --pdb

🔄 Git Workflow

Before Committing

# 1. Ensure Docker services are running
docker ps

# 2. Run backend tests in Docker
docker exec serelo_api python -m pytest tests/ -v

# 3. Run frontend tests on host
cd frontend
npm test

# 4. Build frontend to check for errors
npm run build

# 5. Stage and commit
git add .
git commit -m "feat: description of changes"

CI/CD Note

GitHub Actions will:

Run backend tests in Docker containers (with MongoDB, Redis services)
Run frontend E2E tests with Playwright
Run frontend unit tests
Check TypeScript compilation
Check linting

All tests must pass before merging to main.

⚙️ Environment Variables

Backend (.env or docker-compose.yml)

# Database
MONGODB_URL=mongodb://mongodb:27017
MONGODB_DB_NAME=serelo_db

# Cache
REDIS_URL=redis://redis:6379

# Storage
S3_ENDPOINT=http://minio:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET_NAME=serelo-sources

# Authentication
JWT_SECRET_KEY=your-secret-key-here
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=15
REFRESH_TOKEN_EXPIRE_DAYS=30

# Testing
TEST_MODE=true
TESTING=1  # Set in conftest.py for tests

# Payment (optional)
PAYSTACK_SECRET_KEY=sk_test_...
PAYSTACK_PUBLIC_KEY=pk_test_...

Frontend (.env.local)

VITE_API_URL=http://localhost:8000

🚨 Common Issues and Solutions

Issue: Backend tests fail with "Database not initialized"

Cause: Tests run on host instead of Docker

Solution:

# ❌ Wrong
python -m pytest tests/test_auth.py

# ✅ Correct
docker exec serelo_api python -m pytest tests/test_auth.py

Issue: Tests fail with connection errors

Cause: Docker services not running or not ready

Solution:

# Check services are running
docker ps

# Restart if needed
docker compose down
docker compose up -d --build

# Wait for services to be healthy (check logs)
docker compose logs -f

Issue: Changes not reflected in Docker

Cause: Need to rebuild for non-mounted files

Solution:

# For conftest.py, requirements.txt, or Dockerfile changes
docker compose down
docker compose up -d --build

Issue: Frontend can't connect to backend

Cause: Backend not running or wrong URL

Solution:

# Check backend is accessible
curl http://localhost:8000/health

# Check frontend env
cat frontend/.env.local
# Should have: VITE_API_URL=http://localhost:8000

Issue: Port conflicts

Cause: Ports already in use

Solution:

# Find process using port 8000
netstat -ano | findstr :8000

# Kill process (replace <PID> with actual PID)
taskkill /PID <PID> /F

# Or change ports in docker-compose.yml

📚 Additional Resources

Documentation

Frontend Architecture: docs/_rules/frontend-architecture.md
Backend API: docs/plans/backend-api.md
Design System: docs/_rules/design-system.md
Release Plans: docs/releases/

API Documentation

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

External Links

🤖 AI Assistant Quick Reference

Testing Commands Cheat Sheet

# Frontend Tests (Host) ✅
cd frontend
npm test                                    # Run all
npm test -- --watch                         # Watch mode
npm test -- Button.test.tsx                 # Specific file

# Backend Tests (Docker) ✅
docker exec serelo_api python -m pytest tests/ -v                    # All tests
docker exec serelo_api python -m pytest tests/test_auth.py -v       # One file
docker exec serelo_api python -m pytest tests/test_auth.py::test_register_success -v  # One test

# Backend Tests (Host) ❌ NEVER DO THIS
python -m pytest tests/  # Will fail - no DB/Redis access

Build Commands

# Rebuild backend (after conftest.py or requirements.txt changes)
docker compose down
docker compose up -d --build

# Build frontend (check for compilation errors)
cd frontend
npm run build

Verification Commands

# Check services status
docker ps

# Check backend health
curl http://localhost:8000/health

# Check frontend is running
curl http://localhost:5173

Common Workflows

Scenario 1: Fixed a bug in backend

# 1. Run tests in Docker
docker exec serelo_api python -m pytest tests/test_auth.py -v

# 2. If all pass, commit
git add backend/app/api/auth.py
git commit -m "fix: description"

Scenario 2: Added new test fixtures

# 1. Rebuild Docker (conftest.py changed)
docker compose down
docker compose up -d --build

# 2. Run tests in Docker
docker exec serelo_api python -m pytest tests/ -v

# 3. Commit
git add tests/conftest.py
git commit -m "test: add test_user fixture"

Scenario 3: Frontend changes

# 1. Run tests on host
cd frontend
npm test

# 2. Build to verify
npm run build

# 3. Commit
git add src/
git commit -m "feat: add retry utility"

✅ Summary

Golden Rules

Frontend tests: Run on host with npm test
Backend tests: Run in Docker with docker exec serelo_api python -m pytest
Always rebuild Docker after changing conftest.py, requirements.txt, or Dockerfile
Check all tests pass before committing
Frontend dev server runs on host for fast hot reload
Backend services run in Docker for consistency

Test Verification Checklist

Before declaring "tests fixed" or "tests passing":

Docker containers are running (docker ps)
Tests run inside Docker container (docker exec serelo_api ...)
All tests pass (not just collection)
No fixture errors
Frontend tests also passing (npm test)

Remember: The backend test environment is completely isolated in Docker. Any test command that doesn't start with docker exec serelo_api is running in the wrong environment and will likely fail!

FilesExpand file tree

DEVELOPMENT_GUIDE.md

Latest commit

History

DEVELOPMENT_GUIDE.md

File metadata and controls

Development Guide - Serelo

🏗️ Local Development Architecture

Overview

🚀 Quick Start

1. Start Backend Services (Docker)

2. Start Frontend Development Server (Host)

🧪 Testing Strategy

Critical Rule for AI Assistants

Frontend Tests (Run on Host)

Backend Tests (Run in Docker)

Why Docker for Backend Tests?

Test Configuration

🔧 Common Development Tasks

Rebuild Backend After Code Changes

View Backend Logs

Access Backend Shell

Database Operations

Clear All Data (Fresh Start)

📁 Project Structure

Key Directories

Mounted Volumes

🐛 Debugging

Frontend Debugging

Backend Debugging

Test Debugging

🔄 Git Workflow

Before Committing

CI/CD Note

⚙️ Environment Variables

Backend (.env or docker-compose.yml)

Frontend (.env.local)

🚨 Common Issues and Solutions

Issue: Backend tests fail with "Database not initialized"

Issue: Tests fail with connection errors

Issue: Changes not reflected in Docker

Issue: Frontend can't connect to backend

Issue: Port conflicts

📚 Additional Resources

Documentation

API Documentation

External Links

🤖 AI Assistant Quick Reference

Testing Commands Cheat Sheet

Build Commands

Verification Commands

Common Workflows

✅ Summary

Golden Rules

Test Verification Checklist