Skip to main content

Getting Started - Developer Setup

This guide will help you set up a complete development environment for the Cimigo Collect Platform. You'll have the backend API, frontend renderer, and documentation site running locally within minutes.

📋 Prerequisites​

Before you begin, ensure you have the following installed:

Required Tools​

  • Docker & Docker Compose (recommended for infrastructure)
  • Git for version control
  • Node.js 18+ for frontend development
  • Python 3.11+ for backend development

Optional (if not using Docker)​

  • PostgreSQL 15+
  • Redis 6+ or KeyDB
  • VS Code with Python and TypeScript extensions
  • Postman or Insomnia for API testing
  • Database client (pgAdmin, DataGrip, or VS Code PostgreSQL extension)

🚀 Quick Setup (5 Minutes)​

1. Clone the Repository​

# Clone the repository
git clone https://github.com/cimigo/survey-service
cd survey-service

# Check the project structure
ls -la

2. Start Infrastructure Services​

# Start PostgreSQL and Redis using Docker
docker-compose up -d postgres redis

# Verify services are running
docker-compose ps

3. Setup Backend API​

# Navigate to backend directory
cd backend

# Install Python dependencies using Poetry
poetry install

# Copy environment configuration
cp .env.example .env

# Run database migrations
poetry run alembic upgrade head

# Start the development server
poetry run uvicorn main:app --reload --port 8001

The backend API is now running at http://localhost:8001

4. Setup Frontend Renderer​

# Navigate to renderer directory (in a new terminal)
cd renderer

# Install Node.js dependencies
npm install

# Copy environment configuration
cp .env.local.example .env.local

# Start the development server
npm run dev

The survey renderer is now running at http://localhost:3000

5. Setup Documentation Site​

# Navigate to documentation directory (in a new terminal)
cd document-site

# Install dependencies
npm install

# Start the documentation server
npm run start

The documentation site is now running at http://localhost:3001

🎯 Verify Your Setup​

Check All Services​

ServiceURLPurpose
Backend APIhttp://localhost:8001Core API endpoints
API Documentationhttp://localhost:8001/docsInteractive API docs (Swagger)
Survey Rendererhttp://localhost:3000Survey display and collection
Documentationhttp://localhost:3001Developer and tenant docs
PostgreSQLlocalhost:5432Database (Docker)
Redislocalhost:6379Cache and queues (Docker)

Test the API​

# Health check
curl http://localhost:8001/health

# Expected response:
# {"status": "healthy", "checks": {"database": true, "redis": true}}

Test the Renderer​

Visit http://localhost:3000 - you should see the survey renderer homepage.

Create Your First Survey​

# Create a test survey using the API
curl -X POST "http://localhost:8001/v1/surveys" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-dev-token" \
  -d '{
    "schema_version": "1.2", 
    "version": 1,
    "survey": {
      "title": "My First Survey",
      "supported_languages": ["en"],
      "pages": [{
        "questions": [{
          "type": "text",
          "title": "What is your name?",
          "required": true
        }]
      }]
    }
  }'

🔧 Development Workflow​

Daily Development Routine​

# 1. Start infrastructure (if not running)
docker-compose up -d postgres redis

# 2. Start backend (Terminal 1)
cd backend
poetry run uvicorn main:app --reload --port 8001

# 3. Start frontend (Terminal 2)  
cd renderer
npm run dev

# 4. Start documentation (Terminal 3) - optional
cd document-site
npm run start

Code Changes and Hot Reload​

  • Backend: FastAPI automatically reloads on Python file changes
  • Frontend: Next.js hot reloads on TypeScript/React changes
  • Documentation: Docusaurus hot reloads on Markdown changes

Database Changes​

# Create a new migration after model changes
cd backend
poetry run alembic revision --autogenerate -m "Description of changes"

# Apply migrations
poetry run alembic upgrade head

# Rollback if needed
poetry run alembic downgrade -1

🔍 Project Structure Overview​

survey-service/
├── backend/                 # FastAPI backend
│   ├── backend/            # Main application code
│   │   ├── api/           # HTTP routes and endpoints
│   │   ├── core/          # Configuration and utilities
│   │   ├── models/        # SQLAlchemy database models
│   │   ├── repositories/  # Data access layer
│   │   ├── schemas/       # Pydantic request/response schemas
│   │   └── services/      # Business logic layer
│   ├── alembic/           # Database migrations
│   ├── tests/             # Backend tests
│   └── pyproject.toml     # Python dependencies
│
├── renderer/               # Next.js survey renderer
│   ├── src/
│   │   ├── components/    # React components
│   │   ├── pages/         # Next.js pages/routes
│   │   ├── types/         # TypeScript type definitions
│   │   └── utils/         # Utility functions
│   ├── public/            # Static assets
│   └── package.json       # Node.js dependencies
│
├── document-site/          # Docusaurus documentation
│   ├── docs/              # Documentation content
│   ├── src/               # Custom React components
│   └── docusaurus.config.js
│
├── docker-compose.yml      # Local development setup
└── README.md

🛠️ Development Tools​

Backend Development​

# Code formatting and linting
cd backend
poetry run black .          # Format code
poetry run isort .          # Sort imports  
poetry run flake8 .         # Lint code
poetry run mypy .           # Type checking

# Run tests
poetry run pytest           # All tests
poetry run pytest -v       # Verbose output
poetry run pytest --cov    # With coverage

# Database operations
poetry run alembic current  # Current migration
poetry run alembic history  # Migration history
poetry run alembic upgrade head  # Apply migrations
poetry run alembic downgrade -1  # Rollback one migration

Frontend Development​

# Code quality
cd renderer
npm run lint               # ESLint
npm run lint:fix          # Fix ESLint issues
npm run type-check        # TypeScript checking
npm run format            # Prettier formatting

# Testing
npm run test              # Jest tests
npm run test:watch        # Watch mode
npm run test:coverage     # With coverage

# Build and deployment
npm run build             # Production build
npm run start             # Production server
npm run analyze           # Bundle analysis

Database Management​

# Connect to development database
docker exec -it survey-service_postgres_1 psql -U postgres -d survey_service

# View tables
\dt

# View specific table
\d surveys

# Exit
\q

Redis Inspection​

# Connect to Redis
docker exec -it survey-service_redis_1 redis-cli

# View all keys
KEYS *

# Get specific key
GET "session:user123"

# Exit
exit

🚨 Troubleshooting​

Common Issues​

Port Already in Use​

# Find process using port 8001
lsof -i :8001

# Kill the process
kill -9 <PID>

# Or use different ports
poetry run uvicorn main:app --reload --port 8002

Docker Services Not Starting​

# Check Docker status
docker-compose ps

# View logs
docker-compose logs postgres
docker-compose logs redis

# Restart services
docker-compose down
docker-compose up -d postgres redis

Database Connection Issues​

# Check PostgreSQL connection
docker exec survey-service_postgres_1 pg_isready

# Reset database (⚠️ destroys data)
docker-compose down -v
docker-compose up -d postgres
cd backend && poetry run alembic upgrade head

Python Package Issues​

# Clear Poetry cache
poetry cache clear pypi --all

# Reinstall packages
rm poetry.lock
poetry install

Node.js Package Issues​

# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Getting Help​

If you encounter issues:

  1. Check the logs in your terminal where services are running
  2. Verify prerequisites are correctly installed
  3. Check port availability - ensure no conflicts
  4. Review the Developer FAQ for common solutions (coming soon)
  5. Open an issue on GitHub with detailed error messages

🎯 Next Steps​

Now that your development environment is set up:

  1. Understand the Codebase Structure - Learn how the code is organized (coming soon)
  2. Read Development Patterns - Understand coding conventions (coming soon)
  3. Explore the API - Learn how to create new endpoints (coming soon)
  4. Try Frontend Development - Work with React components (coming soon)
  5. Write Your First Test - Ensure code quality (coming soon)

Create Your First Feature​

Ready to contribute? Here's a suggested first task:

# 1. Create a new branch
git checkout -b feature/add-my-feature

# 2. Make your changes
# ... edit files ...

# 3. Run tests
cd backend && poetry run pytest
cd renderer && npm run test

# 4. Commit your changes
git add .
git commit -m "Add: my awesome feature"

# 5. Push and create PR
git push origin feature/add-my-feature

Welcome to the Cimigo Collect Platform development team! 🎉