Development Environment

The reptidex development environment provides a mixed architecture with backend services running in Docker and frontend applications running locally for optimal development experience.

Architecture Overview

Services (14 Total)

6 Backend Services (FastAPI + Python 3.12) - Docker containers
1 Backend Package (@repti-logging) - Shared logging library
4 Frontend Applications (Vite + React 19 + TypeScript) - Local development
3 Shared Packages (@reptidex-app/ui, @reptidex-app/core, @reptidex-app/logging) - pnpm workspace
Infrastructure (PostgreSQL, Redis, Nginx) - Docker containers

Technology Stack

Backend: FastAPI, Python 3.12, SQLAlchemy, Pydantic (Docker)
Frontend: Vite, React 19, TypeScript, Tailwind CSS, Radix UI (Local)
Shared Packages: Vite build system, TypeScript, pnpm workspace
Databases: PostgreSQL 15 (6 separate databases), Redis 7
Infrastructure: Docker Compose, Nginx (API Gateway)
Environment Variables: Vite’s import.meta.env for frontend (not process.env)

Prerequisites

System Requirements

Docker Desktop 24.0+
Docker Compose 2.21+
Git 2.30+
8GB+ RAM recommended
20GB+ free disk space

Platform Support

✅ macOS (ARM64 & Intel)
✅ Linux (x86_64 & ARM64)
✅ Windows (WSL2 recommended)

Quick Start

1. Complete Environment Setup

# Clone the development environment repository
git clone https://github.com/reptidex-app/repti-dev.git
cd repti-dev

# One-command setup: clone all repos + start infrastructure
./scripts/dev.sh setup

This command will:

Clone all service repositories into the correct directory structure
Start all infrastructure services (databases, Redis, Nginx)
Prepare the environment for service development

2. Verify Setup

# Check health of all services
./scripts/dev.sh health

# View service status
./scripts/dev.sh status

3. Start Development Services

# Start all services (Docker backend + local frontend)
./scripts/dev.sh up

# Or start specific service groups
./scripts/dev.sh backend up     # Docker backend services only
./scripts/dev.sh frontend up    # Local frontend applications
./scripts/dev.sh infra up       # Infrastructure only

Development Scripts

Main Script: `./scripts/dev.sh`

Our primary development management script provides comprehensive service orchestration:

Setup & Repository Management

# Complete setup (repos + infrastructure)
./scripts/dev.sh setup

# Update/clone repositories only
./scripts/dev.sh repos

Service Management

# Start all services
./scripts/dev.sh up

# Stop all services
./scripts/dev.sh down

# Restart all services
./scripts/dev.sh restart

# View service status
./scripts/dev.sh status

Service Groups

# Backend services (repti-core, repti-animal, etc.) - Docker
./scripts/dev.sh backend up|down|restart

# Frontend applications (web-public, web-breeder, etc.) - Local
./scripts/dev.sh frontend up|down|restart|status|logs

# Infrastructure (databases, redis, nginx) - Docker
./scripts/dev.sh infra up|down|restart

# Note: Shared packages are built via pnpm workspace locally

Development Tasks

# View logs for all services
./scripts/dev.sh logs

# View logs for specific service
./scripts/dev.sh logs repti-core
./scripts/dev.sh logs web-public

# Build/rebuild all services
./scripts/dev.sh build

# Install dependencies
./scripts/dev.sh install

# Open shell in service container
./scripts/dev.sh shell repti-core
./scripts/dev.sh shell web-public

Database & Maintenance

# Reset all databases (⚠️ DATA LOSS)
./scripts/dev.sh reset

# Clean everything (⚠️ DATA LOSS)
./scripts/dev.sh clean

Health Monitoring: `./scripts/health-check.sh`

Advanced health monitoring for all services:

# Quick health check
./scripts/health-check.sh

# Detailed health report
./scripts/health-check.sh -v

# JSON output for scripting
./scripts/health-check.sh -j

# Custom timeout (default: 30s)
./scripts/health-check.sh -t 10

Service URLs & Access

Frontend Applications (Local Development)

Service	Direct URL	Development Mode	Purpose
Web Public	http://localhost:3000	`npm run dev` (local)	Marketing & discovery
Web Breeder	http://localhost:3001	`npm run dev` (local)	Breeder dashboard
Web Admin	http://localhost:3002	`npm run dev` (local)	Admin interface
Web Embed	http://localhost:3003	`npm run dev` (local)	Embeddable widgets

Backend APIs (Docker Services)

Service	URL	Health Check	Container
API Gateway	http://localhost:80	http://localhost:80/health	Nginx
Repti Core	http://localhost:8001	http://localhost:8001/api/v1/health	Docker
Repti Animal	http://localhost:8002	http://localhost:8002/api/v1/health	Docker
Repti Commerce	http://localhost:8003	http://localhost:8003/api/v1/health	Docker
Repti Media	http://localhost:8004	http://localhost:8004/api/v1/health	Docker
Repti Community	http://localhost:8005	http://localhost:8005/api/v1/health	Docker
Repti Ops	http://localhost:8006	http://localhost:8006/api/v1/health	Docker

Database Connections

Database	Host:Port	Database Name
Core	localhost:5432	repti_core_db
Animal	localhost:5433	repti_animal_db
Commerce	localhost:5434	repti_commerce_db
Media	localhost:5435	repti_media_db
Community	localhost:5436	repti_community_db
Ops	localhost:5437	repti_ops_db
Redis	localhost:6379	-

Credentials: reptidex / reptidex_dev_password

Project Structure

After running ./scripts/dev.sh setup, your directory structure will be:

repti-dev/
├── backend/                     # 6 FastAPI microservices
│   ├── repti-core/             # Auth, Config, Billing, Events
│   ├── repti-animal/           # Animals, Lineage, Genetics
│   ├── repti-commerce/         # Marketplace, Sales, Transactions
│   ├── repti-media/            # Files, Rendering, Embeds
│   ├── repti-community/        # Search, Notifications, Community
│   └── repti-ops/              # Admin, Audit, Integrations
├── frontend/                    # 4 Vite + React 19 applications
│   ├── web-public/             # Marketing & discovery (Port 3000)
│   ├── web-breeder/            # Breeder dashboard (Port 3001)
│   ├── web-admin/              # Admin interface (Port 3002)
│   └── web-embed/              # Embeddable widgets (Port 3003)
├── packages/                    # 2 shared packages (pnpm workspace)
│   ├── ui/                     # @reptidex/ui - Radix UI + Tailwind components
│   └── core/                   # @reptidex/core - API clients & utilities
├── templates/                   # Service templates
│   └── fastapi-service-template/ # Backend service template
├── docs/                        # Documentation repository
├── scripts/                     # Development scripts
│   ├── dev.sh                  # Main development script
│   ├── health-check.sh         # Health monitoring
│   ├── nginx.dev.conf          # API gateway config
│   └── init-db-*.sql           # Database initialization
├── docker-compose.dev.yml      # Complete development environment
└── .env.dev.example            # Environment variable template

Creating New Frontend Applications

Frontend Application Template System

Reptidex provides a comprehensive frontend template system for rapidly creating new applications with consistent architecture, tooling, and patterns.

Template Features

✅ Vite + React 19 + TypeScript - Modern development stack
✅ Radix UI + Tailwind CSS - Accessible components with utility styling
✅ Zustand + React Query - Client state and server state management
✅ Vitest + React Testing Library - Comprehensive testing setup
✅ ESLint + Prettier - Code quality and formatting
✅ Docker Support - Development and production containers
✅ Hot Module Replacement - Instant feedback during development

Creating a New Frontend Application

# Create different types of applications
./scripts/setup-frontend-app.sh public-site web-public
./scripts/setup-frontend-app.sh breeder-dashboard web-breeder
./scripts/setup-frontend-app.sh admin-panel web-admin
./scripts/setup-frontend-app.sh widget-gallery web-embed

Application Types & Configurations

Each app type comes with pre-configured features and navigation:

App Type	Features	Port	Purpose
web-public	Search, Community, Marketplace	3000	Marketing & discovery
web-breeder	Auth, Search, Marketplace, Community	3001	Breeder dashboard
web-admin	Auth, Search, Admin, All features	3002	Admin interface
web-embed	Search, Embedding only	3003	Embeddable widgets

Shared Package Templates

Create reusable packages for UI components and business logic:

# Create UI component packages
./scripts/setup-frontend-package.sh components ui
./scripts/setup-frontend-package.sh design-system ui

# Create utility/logic packages
./scripts/setup-frontend-package.sh api-clients core
./scripts/setup-frontend-package.sh business-logic core

Frontend Template Structure

Each generated application includes:

frontend/my-app/
├── src/
│   ├── components/          # Reusable UI components
│   │   └── Layout/         # Layout components (Header, Footer)
│   ├── pages/              # Page components
│   ├── config/             # App configuration with feature flags
│   ├── test/               # Test utilities and setup
│   ├── App.tsx             # Main app component with routing
│   ├── main.tsx            # App entry point with providers
│   └── index.css           # Global styles with Tailwind
├── public/                 # Static assets
├── Dockerfile              # Production container
├── Dockerfile.dev          # Development container
├── nginx.conf              # Production nginx config
├── vite.config.ts          # Vite configuration
├── tailwind.config.js      # Tailwind CSS configuration
├── tsconfig.json           # TypeScript configuration
├── .eslintrc.js            # ESLint configuration
├── .prettierrc             # Prettier configuration
├── vitest.config.ts        # Test configuration
└── package.json            # Dependencies and scripts

Development Workflow

# Start complete environment (backend + frontend + packages)
./scripts/dev.sh up

# Start only frontend services
./scripts/dev.sh frontend up

# Start specific frontend app
./scripts/dev.sh up web-public

# Start shared packages in watch mode
./scripts/dev.sh packages up

# Individual app development
cd frontend/my-app
npm run dev

# Build for production
npm run build

# Run tests
npm run test
npm run test:ui

# Code quality
npm run lint
npm run format
npm run type-check

Frontend Workspace Setup

Set up the complete frontend monorepo workspace:

# Initialize workspace with shared packages
./templates/setup-scripts/setup-workspace.sh

# This creates:
# - packages/ui/     # @reptidex/ui shared component library
# - packages/core/   # @reptidex/core API clients and utilities
# - pnpm workspace configuration
# - TypeScript project references
# - Development scripts

Docker Development

# Start all frontend apps using integrated dev.sh
./scripts/dev.sh frontend up

# Start specific frontend app
./scripts/dev.sh up web-public

# Start complete development environment
./scripts/dev.sh up

# Frontend apps available at:
# - web-public: http://public.reptidex.local (or http://localhost:3000)
# - web-breeder: http://breeder.reptidex.local (or http://localhost:3001)
# - web-admin: http://admin.reptidex.local (or http://localhost:3002)
# - web-embed: http://embed.reptidex.local (or http://localhost:3003)
# - API Gateway: http://localhost:80

# Add local domain mapping to /etc/hosts:
# 127.0.0.1 public.reptidex.local breeder.reptidex.local admin.reptidex.local embed.reptidex.local

Shared Package Integration

All frontend applications automatically include and can use:

// @reptidex/ui components
import { Button, Card, Input, Dialog } from "@reptidex/ui";

// @reptidex/core utilities
import { useAuth, useApi, apiClient } from "@reptidex/core";

// Automatic type safety and tree-shaking
// Hot reload works across package boundaries

VS Code Integration

The workspace includes complete VS Code setup:

Recommended Extensions - Tailwind, Prettier, ESLint, TypeScript
Debug Configurations - Launch any frontend app with F5
Tasks - Build, test, lint, type-check via Ctrl+Shift+P
Settings - Automatic formatting, path intellisense, Tailwind autocomplete

Creating New Backend Services

FastAPI Service Template

reptidex provides a comprehensive FastAPI service template that ensures consistency across all backend services. The template includes all necessary components following our architectural patterns and coding standards.

Template Features

✅ Multi-tenant Architecture: Row-level security with organization context
✅ Repository Pattern: Clean data access layer separation
✅ Service Layer: Business logic encapsulation with hooks
✅ Dependency Injection: FastAPI’s dependency system for auth and database
✅ Comprehensive Testing: Unit, integration, and E2E tests with fixtures
✅ Code Quality: Black, isort, flake8, mypy configurations
✅ Docker Support: Multi-stage builds for development and production
✅ Database Migrations: Alembic with async PostgreSQL support

Creating a New Service

The template setup process has been streamlined to work correctly with existing git repositories:

# 1. Copy template files to existing service directory
# (Assumes the service directory already exists with git initialized)
cp -r templates/fastapi-service-template/* backend/repti-{service-name}/
cp -r templates/fastapi-service-template/.[^.]* backend/repti-{service-name}/ 2>/dev/null || true

# 2. Navigate to service directory and run setup
cd backend/repti-{service-name}
./scripts/setup-service.sh {service-name}

# 3. Customize your service
# - Update models in app/models/
# - Create database schemas in app/schemas/
# - Implement business logic in app/services/
# - Add API endpoints in app/api/v1/endpoints/
# - Write tests in tests/

# 4. Set up database
./scripts/migrate.sh create "initial tables"
./scripts/migrate.sh upgrade

# 5. Start development
./scripts/dev.sh

For Multiple Services: Use the bulk setup approach:

# Set up all remaining services at once
# Create a temporary script for bulk setup
cat > setup-services.sh << 'EOF'
#!/bin/bash
SERVICES=("commerce" "media" "community" "ops")  # Add your services here
TEMPLATE_DIR="templates/fastapi-service-template"

for service in "${SERVICES[@]}"; do
    echo "Setting up repti-$service..."
    cp -r "$TEMPLATE_DIR"/* "backend/repti-$service/"
    cp -r "$TEMPLATE_DIR"/.[^.]* "backend/repti-$service/" 2>/dev/null || true
    cd "backend/repti-$service"
    ./scripts/setup-service.sh "$service"
    cd ../..
    echo "✅ repti-$service complete!"
done
EOF

chmod +x setup-services.sh
./setup-services.sh
rm setup-services.sh

Template Structure

The template provides a complete service structure:

repti-{service}/
├── app/                         # Main application code
│   ├── main.py                  # FastAPI app entry point
│   ├── core/                    # Core configuration
│   │   ├── config.py           # Settings management
│   │   ├── security.py         # Authentication/authorization
│   │   ├── dependencies.py     # Shared dependencies
│   │   └── database.py         # Database connection
│   ├── api/                     # API layer
│   │   ├── deps.py             # API dependencies
│   │   └── v1/                 # API version namespace
│   │       ├── router.py       # Main API router
│   │       └── endpoints/      # Individual endpoint files
│   ├── models/                  # Pydantic models (API layer)
│   ├── repositories/            # Data access layer
│   ├── schemas/                 # Database schemas (SQLAlchemy)
│   ├── services/                # Business logic layer
│   └── utils/                   # Utility functions
├── tests/                       # Comprehensive test suite
│   ├── unit/                   # Unit tests
│   ├── integration/            # Integration tests
│   └── e2e/                    # End-to-end tests
├── migrations/                  # Alembic database migrations
├── scripts/                     # Development scripts
│   ├── setup-service.sh        # Service customization
│   ├── dev.sh                  # Development server
│   ├── test.sh                 # Test runner
│   ├── lint.sh                 # Code quality checks
│   └── migrate.sh              # Migration helpers
├── Dockerfile                   # Production container
├── Dockerfile.dev               # Development container
├── docker-compose.yml           # Service-specific compose
├── requirements.txt             # Production dependencies
├── requirements-dev.txt         # Development dependencies
├── pyproject.toml              # Project configuration
├── alembic.ini                 # Alembic configuration
└── .env.example                # Environment template

Setup Script Features

The setup-service.sh script automatically:

Replaces placeholders with your service name in all configuration files ({service} → servicename, {Service} → Servicename)
Checks for existing database initialization script and uses it if available, or creates a new template
Updates service configuration in app/core/config.py with service-specific settings
Configures Docker Compose with correct service name and database connections
Sets up Alembic with service-specific database URL and migration settings
Creates development scripts (dev.sh, test.sh, lint.sh, migrate.sh) with proper permissions
Initializes environment file (.env) from the customized template
Validates service name format (lowercase letters, numbers, hyphens only)

Setup Process Flow

File Customization: Updates all template files with service-specific names
Database Integration: Links to existing database init scripts or creates new ones
Environment Setup: Creates .env file with service-specific database URLs and settings
Script Generation: Creates all development scripts with proper executable permissions
Validation: Ensures all required files are present and correctly configured

Integration with Development Environment

After creating a new service:

Add to Docker Compose: Include the service in docker-compose.dev.yml
Update development scripts: Add to BACKEND_SERVICES array in scripts/dev.sh
Configure API Gateway: Add routing rules to scripts/nginx.dev.conf
Database setup: Initialize and run migrations
Health checks: Verify the service appears in health monitoring

Current reptidex Services

All reptidex backend services have been successfully set up using this template system:

Service	Purpose	Database	Status
repti-core	Auth, Config, Billing, Events	repti_core_db	✅ Ready
repti-animal	Animals, Lineage, Genetics	repti_animal_db	✅ Ready
repti-commerce	Marketplace, Sales, Transactions	repti_commerce_db	✅ Ready
repti-media	Files, Rendering, Embeds, Content	repti_media_db	✅ Ready
repti-community	Search, Notifications, Community, Ads	repti_community_db	✅ Ready
repti-ops	Admin, Audit, Integrations, Logging	repti_ops_db	✅ Ready

Template System Benefits

This template system ensures all reptidex backend services:

✅ Follow consistent architectural patterns (Repository, Service Layer, Dependency Injection)
✅ Maintain high code quality with automated linting, formatting, and type checking
✅ Integrate seamlessly with the development environment and database setup
✅ Support multi-tenant architecture with Row-Level Security (RLS) policies
✅ Include comprehensive testing (unit, integration, end-to-end) from day one
✅ Provide identical development experience across all services
✅ Enable rapid service creation with minimal manual configuration

Creating Additional Services

For future services (e.g., analytics, reporting, webhooks):

# 1. Create git repository structure first
mkdir -p backend/repti-analytics
cd backend/repti-analytics
git init

# 2. Copy template and set up
cd ../..
cp -r templates/fastapi-service-template/* backend/repti-analytics/
cp -r templates/fastapi-service-template/.[^.]* backend/repti-analytics/ 2>/dev/null || true
cd backend/repti-analytics
./scripts/setup-service.sh analytics

# 3. Customize for your specific service
# - Add service-specific models in app/models/
# - Create domain endpoints in app/api/v1/endpoints/
# - Implement business logic in app/services/

# 4. Set up database and start development
./scripts/migrate.sh create "create initial tables"
./scripts/migrate.sh upgrade
./scripts/dev.sh

Database Setup & Migrations

Alembic Integration

Our database initialization scripts are designed to work seamlessly with Alembic:

Database Setup (extensions, roles, RLS policies)
Alembic Migrations (table schemas)
Sample Data (development data)

Setup Sequence

# 1. Start infrastructure
./scripts/dev.sh infra up

# 2. Initialize databases (extensions, roles, functions)
# This happens automatically via Docker init scripts

# 3. Run Alembic migrations (when services have them)
cd backend/repti-core && alembic upgrade head
cd backend/repti-animal && alembic upgrade head
# ... repeat for other services

# 4. Apply RLS policies and sample data
docker exec reptidex-postgres-core psql -U reptidex -d repti_core_db -c "SELECT apply_core_rls_policies();"
docker exec reptidex-postgres-core psql -U reptidex -d repti_core_db -c "SELECT insert_core_sample_data();"
# ... repeat for other databases

Database Utilities

Each database has helper functions for post-migration setup:

-- Apply RLS policies after Alembic creates tables
SELECT apply_core_rls_policies();
SELECT apply_animal_rls_policies();
SELECT apply_commerce_rls_policies();
-- ... etc

-- Insert development sample data
SELECT insert_core_sample_data();
SELECT insert_animal_sample_data();
SELECT insert_commerce_sample_data();
-- ... etc

Development Workflow

Daily Development

# 1. Update all repositories
./scripts/dev.sh repos

# 2. Start your working services
./scripts/dev.sh backend up      # For backend development
./scripts/dev.sh frontend up     # For frontend development
./scripts/dev.sh packages up     # For shared package development
./scripts/dev.sh up              # For full-stack development

# 3. Monitor services
./scripts/dev.sh health
./scripts/dev.sh logs repti-core
./scripts/dev.sh logs web-public

Integrated Frontend & Backend

The development environment provides seamless integration between frontend and backend:

Service Communication

API Gateway: Nginx at port 80 routes requests to appropriate services
Frontend → Backend: Apps automatically proxy /api/* requests through the gateway
Domain-based routing: Each frontend app has its own subdomain for isolation
Hot reload: Changes in frontend apps and shared packages trigger immediate updates
Shared packages: UI and core packages automatically rebuild and link to apps

Development Flow

# Start complete environment
./scripts/dev.sh up

# Make changes to shared packages - they auto-rebuild
# Make changes to frontend apps - they auto-reload
# Make changes to backend services - they auto-restart

# Access applications:
# - API docs: http://localhost:80/docs
# - Public site: http://public.reptidex.local
# - Breeder dashboard: http://breeder.reptidex.local
# - Admin panel: http://admin.reptidex.local

# Monitor all services
./scripts/dev.sh status
./scripts/dev.sh health

Hot Reload Development

All services are configured with volume mounts for instant code changes:

Backend: FastAPI auto-reload on Python file changes
Frontend: Vite HMR (Hot Module Replacement)
Shared Packages: Watch mode with automatic rebuilding

Working with Individual Services

# Open shell in any service
./scripts/dev.sh shell repti-core
./scripts/dev.sh shell web-public

# Install dependencies
cd backend/repti-core && pip install -r requirements.txt
cd frontend/web-public && npm install

# Run service-specific commands
cd backend/repti-core && pytest
cd frontend/web-public && npm run test

Environment Configuration

Environment Variables

Copy and customize the environment template:

cp .env.dev.example .env.dev
nano .env.dev

Key Configuration Sections

Database URLs: Individual connection strings for each service
Service URLs: Internal Docker network communication
Frontend API URLs: External URLs for browser access
Multi-tenant Settings: Default organization and tenant headers
Feature Flags: Development-specific toggles

Example Configuration

# Core service database
CORE_DATABASE_URL=postgresql://reptidex:reptidex_dev_password@postgres-core:5432/repti_core_db

# Animal service database
ANIMAL_DATABASE_URL=postgresql://reptidex:reptidex_dev_password@postgres-animal:5432/repti_animal_db

# Redis configuration
REDIS_URL=redis://redis:6379

# Frontend API endpoints (accessed via import.meta.env)
VITE_API_BASE_URL=http://localhost:80
VITE_WS_URL=ws://localhost:80/ws

Troubleshooting

Common Issues

Services Won’t Start

# Check Docker is running
docker info

# Check for port conflicts
netstat -tulpn | grep :3000
netstat -tulpn | grep :8001

# Rebuild services
./scripts/dev.sh build

# Reset everything
./scripts/dev.sh clean
./scripts/dev.sh setup

Database Connection Issues

# Check database health
./scripts/dev.sh health

# View database logs
./scripts/dev.sh logs postgres-core

# Reset databases
./scripts/dev.sh reset

# Manual database connection test
docker exec -it reptidex-postgres-core psql -U reptidex -d repti_core_db

Frontend Build Issues

# Check Node.js version (requires 18+)
node --version

# Clear node_modules and rebuild
./scripts/dev.sh clean
./scripts/dev.sh build

# Install dependencies manually
cd frontend/web-public
rm -rf node_modules package-lock.json
npm install

# Common frontend issues:
# 1. "process is not defined" error
#    Fix: Use import.meta.env instead of process.env in frontend code
# 2. Environment variables not loading
#    Fix: Ensure variables start with VITE_ prefix
# 3. Shared package import errors
#    Fix: Run pnpm install in project root to link workspace packages

API Gateway Issues

# Check nginx logs
./scripts/dev.sh logs nginx

# Test backend services directly
curl http://localhost:8001/health
curl http://localhost:8002/health

# Restart API gateway
docker-compose -f docker-compose.dev.yml restart nginx

Repository Management Issues

# Manual repository update
cd backend/repti-core
git fetch origin
git pull origin main

# Reclone specific repository
rm -rf backend/repti-core
./scripts/dev.sh repos

Performance Issues

# Check resource usage
docker stats

# Check disk space
df -h

# Optimize Docker resources
docker system prune -f

# Increase Docker memory limits in Docker Desktop
# Go to Preferences → Resources → Advanced

Log Analysis

# Follow all logs
./scripts/dev.sh logs

# Filter specific service errors
./scripts/dev.sh logs repti-core | grep ERROR

# Save logs to file for analysis
./scripts/dev.sh logs > debug.log 2>&1

# Structured log analysis with jq
./scripts/health-check.sh -j | jq '.services[] | select(.status != "healthy")'

Advanced Usage

Custom Service Configurations

Each service can be customized by modifying its section in docker-compose.dev.yml:

services:
  repti-core:
    build:
      context: ./backend/repti-core
      dockerfile: Dockerfile.dev
    environment:
      - DEBUG=true
      - LOG_LEVEL=debug
    volumes:
      - ./backend/repti-core:/app
    ports:
      - "8001:8000"

Network Configuration

Services communicate through Docker networks:

External Network: Browser → Nginx (port 80) → Backend Services
Internal Network: Service-to-service communication via service names
Database Network: Services → PostgreSQL/Redis via internal hostnames

Volume Management

# List all volumes
docker volume ls | grep reptidex

# Inspect volume contents
docker volume inspect reptidex_postgres_core_data

# Backup database volume
docker run --rm -v reptidex_postgres_core_data:/data -v $(pwd):/backup alpine tar czf /backup/core_db_backup.tar.gz -C /data .

# Restore database volume
docker run --rm -v reptidex_postgres_core_data:/data -v $(pwd):/backup alpine tar xzf /backup/core_db_backup.tar.gz -C /data

Multi-Platform Development

The environment supports ARM64 and AMD64 architectures:

# Automatic platform detection in docker-compose.dev.yml
services:
  repti-core:
    platform: linux/amd64 # Force specific platform if needed
    build:
      context: ./backend/repti-core
      platforms:
        - linux/amd64
        - linux/arm64

Security Considerations

Development Security

Credentials: Use only development credentials (never production)
Network: Services isolated within Docker networks
Data: Local development data only
Access: No external access to development databases

Environment Isolation

# Development environment is completely isolated
# - Uses separate .env.dev configuration
# - Runs on non-standard ports
# - Contains no production data or credentials
# - Cannot access production services

Secret Management

# Never commit secrets to repositories
# Use .env.dev for local development secrets
# Use environment-specific secret management for other environments

Getting Help

Documentation Resources

Architecture Overview
Coding Standards
Getting Started
API Documentation (when services are running)

Team Communication

Slack: #engineering-general for questions
Slack: #development-environment for setup issues
GitHub Issues: For bugs and feature requests
Team Wiki: Internal documentation and runbooks

Self-Service Debugging

Check service health: ./scripts/dev.sh health
Review logs: ./scripts/dev.sh logs [service]
Verify configuration: Check .env.dev file
Test connectivity: Use health check endpoints
Restart services: ./scripts/dev.sh restart

For complex issues, gather the following information before asking for help:

# Collect debug information
./scripts/dev.sh status > debug-status.txt
./scripts/health-check.sh -v > debug-health.txt
docker system info > debug-docker.txt

Contributing to the Development Environment

Making Changes

Test locally: Verify changes work in your environment
Update documentation: Update this file for any changes
Test setup from scratch: ./scripts/dev.sh clean && ./scripts/dev.sh setup
Create PR: Include testing steps and migration notes

Common Improvement Areas

Performance: Optimize build times and resource usage
Developer Experience: Improve scripts and automation
Documentation: Keep guides current and comprehensive
Compatibility: Support new platforms and Docker versions

The development environment is continuously evolving to support the needs of the reptidex engineering team. Your feedback and contributions help make it better for everyone! 🚀

Getting Started

System Architecture

Backend Services

Frontend Applications

Shared Packages

Development Standards

Infrastructure & Operations

API Reference

​Development Environment

​Architecture Overview

​Services (14 Total)

​Technology Stack

​Prerequisites

​System Requirements

​Platform Support

​Quick Start

​1. Complete Environment Setup

​2. Verify Setup

​3. Start Development Services

​Development Scripts

​Main Script: ./scripts/dev.sh

​Setup & Repository Management

​Service Management

​Service Groups

​Development Tasks

​Database & Maintenance

​Health Monitoring: ./scripts/health-check.sh

​Service URLs & Access

​Frontend Applications (Local Development)

​Backend APIs (Docker Services)

​Database Connections

​Project Structure

​Creating New Frontend Applications

​Frontend Application Template System

​Template Features

​Creating a New Frontend Application

​Application Types & Configurations

​Shared Package Templates

​Frontend Template Structure

​Development Workflow

​Frontend Workspace Setup

​Docker Development

​Shared Package Integration

​VS Code Integration

​Creating New Backend Services

​FastAPI Service Template

​Template Features

​Creating a New Service

​Template Structure

​Setup Script Features

​Setup Process Flow

​Integration with Development Environment

​Current reptidex Services

​Template System Benefits

​Creating Additional Services

​Database Setup & Migrations

​Alembic Integration

​Setup Sequence

​Database Utilities

​Development Workflow

​Daily Development

​Integrated Frontend & Backend

​Service Communication

​Development Flow

​Hot Reload Development

​Working with Individual Services

​Environment Configuration

​Environment Variables

​Key Configuration Sections

​Example Configuration

​Troubleshooting

​Common Issues

​Services Won’t Start

​Database Connection Issues

​Frontend Build Issues

​API Gateway Issues

​Repository Management Issues

​Performance Issues

​Log Analysis

​Advanced Usage

Development Environment

Architecture Overview

Services (14 Total)

Technology Stack

Prerequisites

System Requirements

Platform Support

Quick Start

1. Complete Environment Setup

2. Verify Setup

3. Start Development Services

Development Scripts

Main Script: `./scripts/dev.sh`

Setup & Repository Management

Service Management

Service Groups

Development Tasks

Database & Maintenance

Health Monitoring: `./scripts/health-check.sh`

Service URLs & Access

Frontend Applications (Local Development)

Backend APIs (Docker Services)

Database Connections

Project Structure

Creating New Frontend Applications

Frontend Application Template System

Template Features

Creating a New Frontend Application

Application Types & Configurations

Shared Package Templates

Frontend Template Structure

Development Workflow

Frontend Workspace Setup

Docker Development

Shared Package Integration

VS Code Integration

Creating New Backend Services

FastAPI Service Template

Template Features

Creating a New Service

Template Structure

Setup Script Features

Setup Process Flow

Integration with Development Environment

Current reptidex Services

Template System Benefits

Creating Additional Services

Database Setup & Migrations

Alembic Integration

Setup Sequence

Database Utilities

Development Workflow

Daily Development

Integrated Frontend & Backend

Service Communication

Development Flow

Hot Reload Development

Working with Individual Services

Environment Configuration

Environment Variables

Key Configuration Sections

Example Configuration

Troubleshooting

Common Issues

Services Won’t Start

Database Connection Issues

Frontend Build Issues

API Gateway Issues

Repository Management Issues

Performance Issues

Log Analysis

Advanced Usage

Custom Service Configurations

Network Configuration

Volume Management

Multi-Platform Development

Security Considerations

Development Security

Environment Isolation

Secret Management