Getting Started

Welcome to ReptiDex Engineering

This guide will help you get up and running with the ReptiDex development environment and understand our engineering practices.

Prerequisites

Required Software

Node.js: Version 18+ (use nvm for version management)
Python: Version 3.11+ (use pyenv for version management)
Docker: Latest stable version with Docker Compose
Git: Latest version with SSH key configuration
VS Code: Recommended IDE with suggested extensions

Required Accounts

GitHub: Access to reptidex organization repositories
AWS: Development account access (provided by DevOps)
Slack: Team communication and integration notifications
Linear: Project management and issue tracking

Development Environment Setup

1. Repository Setup

# Clone the main repository
git clone [email protected]:ReptiDex/reptidex.git
cd reptidex

# Set up git configuration
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

2. Quick Start with Scripts

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

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

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

# Or start specific service groups
./scripts/dev.sh backend up
./scripts/dev.sh frontend up
./scripts/dev.sh infra up

3. Manual Docker Compose Setup

# Start all development services
docker-compose -f docker-compose.dev.yml up -d

# Start only infrastructure (DB, Redis, etc.)
docker-compose -f docker-compose.dev.yml up -d postgres-core postgres-animal redis nginx

# View logs
docker-compose -f docker-compose.dev.yml logs -f [service-name]

📖 For comprehensive setup instructions, troubleshooting, and advanced usage, see our detailed Development Environment Guide.

Project Structure

Monorepo Organization

├── backend/           # Backend microservices (FastAPI + Python)
│   ├── shared/        # Shared Python packages
|       ├── repti-logging/      # Centralized logging & telemetry
│   ├── 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/          # Frontend applications (Vite + React 19) - Run locally
│   ├── web-public/    # Marketing & discovery (Port 3000)
│   ├── web-breeder/   # Breeder dashboard (Port 3001)
│   ├── web-admin/     # Admin interface (Port 3002)
│   └── web-embed/     # Embeddable widgets (Port 3003)
├── infrastructure/            # Cloudformation templates & scripts
├── packages/          # Shared frontend packages
│   ├── ui/           # @reptidex-app/ui - Radix UI + Tailwind components
│   ├── logging/      # @reptidex-app/logging - Frontend logging & telemetry
│   └── core/         # @reptidex-app/core - API clients & utilities
├── scripts/           # Development & deployment automation
├── templates/         # Code generation templates
│   ├── fastapi-service-template/    # Backend service template
│   ├── frontend-app-template/       # Frontend app template
│   ├── shared-ui-package-template/  # UI package template
│   └── shared-core-package-template/ # Core package template
└── docs/             # Documentation

Service Architecture

API Gateway: All external requests go through Nginx on port 80
Backend Services: Run in Docker on ports 8001-8006 (repti-core to repti-ops)
Frontend Applications: Run locally via npm/pnpm on ports 3000-3003
Shared Packages: Built locally via pnpm workspace (@reptidex/ui, @reptidex/core)
Databases: PostgreSQL instances on ports 5432-5437 (one per service)
Infrastructure: Redis (6379), shared across services

Development Workflow

1. Feature Development

Create Branch: git checkout -b feature/your-feature-name
Develop: Write code following our coding standards
Test: Run unit tests and integration tests
Review: Create pull request for code review
Deploy: Merge to main triggers automatic deployment

2. Code Review Process

All code must be reviewed by at least one team member
Automated tests must pass before merge
Follow established patterns and conventions
Update documentation as needed

3. Testing Strategy

Unit Tests: Jest for JavaScript, pytest for Python
Integration Tests: API and database integration testing
E2E Tests: Playwright for critical user journeys
Manual Testing: QA review for UI/UX changes

Coding Standards

Code Style

TypeScript: Strict mode enabled, comprehensive typing
Python: PEP 8 compliance, type hints required
Formatting: Prettier for JS/TS, Black for Python
Linting: ESLint for JS/TS, Flake8 for Python
Testing: Minimum 70% coverage, focus on critical paths

Best Practices

Write self-documenting code with clear variable names
Include comprehensive error handling and logging
Follow SOLID principles and clean architecture patterns
Write tests for all new functionality
Update documentation for API and architectural changes

Development Scripts Overview

Unified Development Script: `./scripts/dev.sh`

Our main development script now provides seamless management of both Docker backend services and local frontend applications:

# One-stop commands
./scripts/dev.sh up                     # Start everything (backend + frontend)
./scripts/dev.sh down                   # Stop everything
./scripts/dev.sh health                 # Check all services
./scripts/dev.sh status                 # View Docker service status

# Service group management
./scripts/dev.sh backend up|down|restart    # Docker backend services
./scripts/dev.sh frontend up|down|restart   # Local frontend apps
./scripts/dev.sh infra up|down|restart      # Infrastructure services

# Frontend-specific commands
./scripts/dev.sh frontend status           # Check which apps are running
./scripts/dev.sh frontend logs [app]       # View frontend app logs

Available Scripts

Frontend Development

# Frontend development commands (using unified dev.sh)
./scripts/dev.sh frontend up            # Start all frontend apps locally
./scripts/dev.sh frontend down           # Stop all frontend apps
./scripts/dev.sh frontend status         # Check frontend app status
./scripts/dev.sh frontend logs [app]     # View logs for specific app
./scripts/dev.sh frontend restart        # Restart all frontend apps
./scripts/dev.sh up                     # Start complete environment (backend + frontend)

# Individual app development (alternative)
cd frontend/web-public && npm run dev   # Port 3000
cd frontend/web-breeder && npm run dev  # Port 3001
cd frontend/web-admin && npm run dev    # Port 3002
cd frontend/web-embed && npm run dev    # Port 3003

# Package development (automatic via pnpm workspace)
pnpm install                            # Install all dependencies
pnpm build                              # Build shared packages

Development Environment

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

# Start service groups
./scripts/dev.sh backend up             # Docker backend services only
./scripts/dev.sh frontend up            # Local frontend apps only
./scripts/dev.sh infra up               # Infrastructure only

# Stop services
./scripts/dev.sh down                   # Stop all (backend + frontend)
./scripts/dev.sh backend down           # Stop backend services
./scripts/dev.sh frontend down          # Stop frontend apps

# Check status and health
./scripts/dev.sh status                 # Docker service status
./scripts/dev.sh health                 # All services health check
./scripts/dev.sh logs [service-name]    # View service logs

Docker Compose Commands

# Start all development services
docker-compose -f docker-compose.dev.yml up -d

# Start infrastructure only
docker-compose -f docker-compose.dev.yml up -d db cache rabbitmq otel-collector jaeger

# Rebuild and restart service
docker-compose -f docker-compose.dev.yml up -d --build repti-auth

# View logs
docker-compose -f docker-compose.dev.yml logs -f repti-auth
docker-compose -f docker-compose.dev.yml logs -f web-portal

# Stop all services
docker-compose -f docker-compose.dev.yml down

# Stop and remove volumes
docker-compose -f docker-compose.dev.yml down -v

Individual Service Development

# Backend services (Python/FastAPI) - via Docker
./scripts/dev.sh logs repti-core         # View logs
./scripts/dev.sh shell repti-core        # Access service shell

# Frontend applications (Vite + React) - run locally
cd frontend/web-public && npm run dev   # Direct development
./scripts/dev.sh frontend logs web-public  # View app logs

Database & Infrastructure

# Initialize database
./scripts/bulk-ops.sh init-db

# Access PostgreSQL
docker-compose -f docker-compose.dev.yml exec db psql -U repti -d ReptiDex_dev

# Access Redis CLI
docker-compose -f docker-compose.dev.yml exec cache redis-cli

# View RabbitMQ Management UI
open http://localhost:15672  # repti/repti

# View Jaeger Tracing UI
open http://localhost:16686

# View PgAdmin
open http://localhost:5050   # [email protected]/admin

# View Redis Commander
open http://localhost:8081

Getting Help

Documentation

Service Documentation: /docs/engineering/services/ - Individual service specs
Architecture Documentation: /docs/engineering/architecture/ - System design
Application Documentation: /docs/engineering/applications/ - Frontend apps
API Documentation: Auto-generated from OpenAPI specs
Development Tools: DEVELOPMENT-TOOLS.md in project root

Team Communication

Daily Standups: 9:00 AM EST via Slack/Video
Office Hours: Engineering leads available 2-4 PM EST
Slack Channels: #engineering, #random, #releases
Code Reviews: GitHub notifications and Slack integration

Development Tools & Debugging

Logs: Docker Compose logs via docker-compose logs -f [service]
Observability: Jaeger tracing at http://localhost:16686
Database: PgAdmin at http://localhost:5050
Cache: Redis Commander at http://localhost:8081
Message Queue: RabbitMQ Management at http://localhost:15672
Email Testing: MailHog at http://localhost:8025
Local Debugging: VS Code debugging configuration provided

Development Scripts

./scripts/dev.sh: Complete development environment management
./scripts/bulk-ops.sh: Bulk operations across services
./scripts/service-registry.sh: Service discovery and registry management
./scripts/generate-docs.sh: Documentation generation
./scripts/setup-shared-workflows.sh: CI/CD workflow setup

Next Steps

Environment Verification:

# Start the development environment
./scripts/dev.sh start

# Verify all services are healthy
./scripts/dev.sh status

# Access the main portal
open http://localhost:3002

Service Exploration:
- Visit http://localhost:8000 for the API Gateway
- Check out individual service documentation in /docs/engineering/services/
- Review the system architecture in /docs/engineering/architecture/
First Development Task:
- Pick up a “good first issue” from Linear
- Create a feature branch following our naming conventions
- Test your changes using the development environment
Team Integration:
- Schedule 1:1s with team members
- Join daily standups and planning meetings
- Familiarize yourself with our coding standards and review process
Deep Dive:
- Explore the microservice templates in /templates/
- Review shared libraries in /libraries/
- Understand our deployment and CI/CD processes

Troubleshooting

Common Issues

Port conflicts: Check if ports 3000-3007, 8000-8013, 5432, 6379 are available
Docker issues: Run docker system prune to clean up containers and volumes
Service startup failures: Check logs with ./scripts/dev.sh logs [service-name]
Database connection issues: Ensure PostgreSQL is running and accessible

Quick Fixes

# Reset development environment
./scripts/dev.sh stop
docker-compose -f docker-compose.dev.yml down -v
./scripts/dev.sh start

# Rebuild specific service
docker-compose -f docker-compose.dev.yml up -d --build [service-name]

# Check service health
curl http://localhost:8000/health  # API Gateway health check

Welcome to the ReptiDex engineering team! 🦎

Getting Started

System Architecture

Backend Services

Frontend Applications

Shared Packages

Development Standards

Infrastructure & Operations

API Reference

​Getting Started

​Welcome to ReptiDex Engineering

​Prerequisites

​Required Software

​Required Accounts

​Development Environment Setup

​1. Repository Setup

​2. Quick Start with Scripts

​3. Manual Docker Compose Setup

​Project Structure

​Monorepo Organization

​Service Architecture

​Development Workflow

​1. Feature Development

​2. Code Review Process

​3. Testing Strategy

​Coding Standards

​Code Style

​Best Practices

​Development Scripts Overview

​Unified Development Script: ./scripts/dev.sh

​Available Scripts

​Frontend Development

​Development Environment

​Docker Compose Commands

​Individual Service Development

​Database & Infrastructure

​Getting Help

​Documentation

​Team Communication

​Development Tools & Debugging

​Development Scripts

​Next Steps

​Troubleshooting

​Common Issues

​Quick Fixes

Getting Started

Welcome to ReptiDex Engineering

Prerequisites

Required Software

Required Accounts

Development Environment Setup

1. Repository Setup

2. Quick Start with Scripts

3. Manual Docker Compose Setup

Project Structure

Monorepo Organization

Service Architecture

Development Workflow

1. Feature Development

2. Code Review Process

3. Testing Strategy

Coding Standards

Code Style

Best Practices

Development Scripts Overview

Unified Development Script: `./scripts/dev.sh`

Available Scripts

Frontend Development

Development Environment

Docker Compose Commands

Individual Service Development

Database & Infrastructure

Getting Help

Documentation

Team Communication

Development Tools & Debugging

Development Scripts

Next Steps

Troubleshooting

Common Issues

Quick Fixes