Developer Documentation
Welcome to the Developer Documentation for the Cimigo Collect Platform. This section is designed for developers who want to:
- 🏗️ Contribute to the platform codebase
- 🔧 Extend platform functionality
- 🚀 Deploy the platform for organizations
- 🔍 Understand the technical architecture
🚦 Quick Start for Developers
Prerequisites
- Docker & Docker Compose - For local development
- Node.js 18+ - For frontend development
- Python 3.11+ - For backend development
- PostgreSQL 15+ - For database (or use Docker)
- Redis/KeyDB - For caching and queues (or use Docker)
Local Development Setup
# 1. Clone the repository
git clone https://github.com/cimigo/survey-service
cd survey-service
# 2. Start infrastructure services
docker-compose up -d postgres redis
# 3. Setup backend
cd backend
poetry install
poetry run alembic upgrade head
poetry run uvicorn main:app --reload --port 8001
# 4. Setup frontend renderer
cd ../renderer
npm install
npm run dev # Runs on port 3000
# 5. Setup documentation site
cd ../document-site
npm install
npm run start # Runs on port 3001
Access Points:
- 🔧 API Server: http://localhost:8001
- 🎨 Survey Renderer: http://localhost:3000
- 📚 Documentation: http://localhost:3001
- 📊 API Docs: http://localhost:8001/docs
🏗️ Architecture Overview
The Cimigo Collect Platform follows a modular, domain-driven architecture designed for scalability and maintainability.
Core Components
| Component | Technology | Purpose | Port |
|---|---|---|---|
| Backend API | FastAPI + Python | Core business logic, API endpoints | 8001 |
| Survey Renderer | Next.js + React | Survey display and response collection | 3000 |
| Database | PostgreSQL | Primary data storage with multi-tenancy | 5432 |
| Cache & Queue | Redis/KeyDB | Session storage, caching, webhook queue | 6379 |
| Documentation | Docusaurus | Developer and tenant documentation | 3001 |
📚 Developer Guide Sections
🏗️ Architecture & Design
Deep dive into the technical foundation:
- System Architecture - High-level system design
- Database Design - Schema, migrations, patterns (Coming Soon)
- Multi-tenancy - Tenant isolation strategies (Coming Soon)
- Security Architecture - Authentication, authorization, data protection (Coming Soon)
- Performance - Caching, optimization, scaling (Coming Soon)
🔧 Development Workflow
Getting productive with the codebase:
- Getting Started - Environment setup and first steps
- Codebase Structure - Understanding the project layout (Coming Soon)
- Development Patterns - Coding conventions and best practices (Coming Soon)
- Testing Guide - Unit, integration, and E2E testing (Coming Soon)
- Debugging - Tools and techniques for troubleshooting (Coming Soon)
🚀 API Development
Building and extending the platform:
- API Development - Creating new endpoints (Coming Soon)
- Database Operations - Working with SQLAlchemy and migrations (Coming Soon)
- Background Tasks - Async processing and queues (Coming Soon)
- Authentication - JWT, API keys, permissions (Coming Soon)
- Validation - Pydantic schemas and data validation (Coming Soon)
🎨 Frontend Development
Working with the survey renderer:
- Renderer Architecture - Next.js structure and patterns (Coming Soon)
- Component Library - Reusable UI components (Coming Soon)
- Question Types - Implementing new question types (Coming Soon)
- Theming System - Customization and branding (Coming Soon)
- State Management - React patterns and data flow (Coming Soon)
🔄 DevOps & Deployment
Running the platform in production:
- Docker Setup - Containerization and orchestration (Coming Soon)
- Production Deployment - Scalable deployment patterns (Coming Soon)
- Monitoring - Observability and alerting (Coming Soon)
- Database Management - Backups, migrations, scaling (Coming Soon)
- CI/CD Pipeline - Automated testing and deployment (Coming Soon)
🤝 Contributing
Joining the development effort:
- Contribution Guidelines - How to contribute effectively (Coming Soon)
- Code Review Process - Standards and practices (Coming Soon)
- Issue Triage - Bug reports and feature requests (Coming Soon)
- Documentation - Keeping docs up to date (Coming Soon)
- Release Process - Versioning and release management (Coming Soon)
🔧 Development Tools & Scripts
Backend Development
# Backend development commands
cd backend
# Install dependencies
poetry install
# Run database migrations
poetry run alembic upgrade head
# Generate new migration
poetry run alembic revision --autogenerate -m "Description"
# Run development server
poetry run uvicorn main:app --reload --port 8001
# Run tests
poetry run pytest
# Run linting and formatting
poetry run black .
poetry run isort .
poetry run flake8 .
poetry run mypy .
Frontend Development
# Renderer development commands
cd renderer
# Install dependencies
npm install
# Run development server
npm run dev
# Build for production
npm run build
# Run tests
npm run test
# Type checking
npm run type-check
# Linting
npm run lint
npm run lint:fix
Database Operations
# Database management
cd backend
# Create new migration
poetry run alembic revision --autogenerate -m "Add new table"
# Apply migrations
poetry run alembic upgrade head
# Rollback migration
poetry run alembic downgrade -1
# View migration history
poetry run alembic history
# Generate SQL for migration (dry run)
poetry run alembic upgrade head --sql
Testing Commands
# Run all tests
docker-compose -f docker-compose.test.yml up --build --abort-on-container-exit
# Backend tests only
cd backend && poetry run pytest
# Frontend tests only
cd renderer && npm run test
# E2E tests
cd e2e && npm run test:e2e
# Performance tests
cd performance && artillery run load-test.yml
📊 Key Metrics & Monitoring
Development Metrics
- Code Coverage: Target >90% for critical paths
- Type Coverage: 100% TypeScript coverage in frontend
- Build Time: <2 minutes for full build
- Test Suite: <30 seconds for unit tests
Performance Targets
- API Response: <200ms for 95th percentile
- Survey Load: <1s for survey rendering
- Database Queries: <50ms for typical operations
- Memory Usage: <512MB per service instance
Quality Gates
- Security Scanning: No high/critical vulnerabilities
- Dependency Updates: Monthly security updates
- Documentation: All public APIs documented
- Backward Compatibility: Semantic versioning compliance
🔍 Common Development Tasks
Adding a New Question Type
- Backend: Create Pydantic schema in
backend/schemas/survey.py - Frontend: Implement React component in
renderer/src/components/questions/ - Validation: Add validation logic in
backend/services/ - Tests: Write unit and integration tests
- Documentation: Update question type documentation
Creating a New API Endpoint
- Schema: Define request/response schemas in
backend/schemas/ - Service: Implement business logic in
backend/services/ - Repository: Add database operations in
backend/repositories/ - Route: Create FastAPI route in
backend/api/routes/ - Tests: Write comprehensive test coverage
- Documentation: Update OpenAPI documentation
Database Schema Changes
- Model: Update SQLAlchemy models in
backend/models/ - Migration: Generate Alembic migration
- Repository: Update repository methods
- Schema: Update Pydantic schemas
- Tests: Update affected tests
- Deployment: Plan migration rollout
🆘 Developer Support
Getting Help
- Developer FAQ - Common technical issues (Coming Soon)
- Debugging Guide - Tools and techniques (Coming Soon)
- Performance Profiling - Optimization strategies (Coming Soon)
- GitHub Discussions - Community support
Useful Resources
- API Documentation - Complete endpoint reference (Coming Soon)
- Database Schema - ERD and table documentation (Coming Soon)
- Coding Standards - Style guides and conventions (Coming Soon)
- Architecture Decisions - Technical decision records (Coming Soon)
🎉 Ready to Contribute?
Ready to start developing? Here's your next steps:
- Set up your development environment (Coming Soon)
- Understand the codebase structure (Coming Soon)
- Read the contribution guidelines (Coming Soon)
- Pick up a good first issue
Welcome to the Cimigo Collect Platform development team! 🚀