Getting Started

Get your DermaDetect development environment up and running in minutes.

Prerequisites

Before you begin, make sure you have:

Python 3.13+ - Download Python
uv - Fast Python package manager (Install uv )
Docker & Docker Compose - Install Docker
just (optional) - Command runner (Install just )

Quick Start

1. Clone the Repository


git clone https://github.com/dermadetect/backend_2025.git
cd backend_2025

2. Install Dependencies


# Using just (recommended)
just install
 
# Or manually
cd packages/py_core && uv sync
cd ../services/ai_service && uv sync
cd ../api_gateway && uv sync

3. Start Local Services


# Start PostgreSQL, AI service, and API gateway
just up
 
# Or manually
docker compose up -d

4. Run Tests


# Test all services
just test
 
# Test specific service
just test-service packages/py_core

5. Access the Services

API Gateway: http://localhost:8000
AI Service: http://localhost:8080
API Docs: http://localhost:8000/docs (Swagger UI)
PostgreSQL: localhost:5432

Project Structure


backend_2025/
├── packages/
│   └── py_core/              # Shared utilities
│       ├── src/
│       │   ├── auth/         # JWT, password hashing
│       │   ├── db/           # Database connections
│       │   ├── models/       # Pydantic models
│       │   └── storage/      # Cloud storage
│       └── pyproject.toml
│
├── services/
│   ├── ai_service/           # AI/ML service
│   │   ├── src/
│   │   │   ├── api/          # FastAPI routes
│   │   │   ├── core/         # Business logic
│   │   │   └── main.py       # Entry point
│   │   └── pyproject.toml
│   │
│   └── api_gateway/          # API gateway
│       ├── src/
│       │   ├── api/
│       │   │   └── v1/       # Versioned routes
│       │   ├── auth/         # Authentication
│       │   └── main.py
│       └── pyproject.toml
│
└── docs/                     # This documentation site

Common Commands

Development


just up              # Start local development stack
just down            # Stop services
just logs            # View all logs
just logs-service postgres  # View specific service logs

Code Quality


just lint            # Run ruff linter and formatter
just pre-commit      # Run pre-commit hooks

Testing


just test            # Run all tests
just test-integration # Run integration tests
just test-service services/ai_service  # Test specific service

Database


just migrate         # Run database migrations
just migrate-create "add_user_table"  # Create new migration

Local Development


just start-ai        # Start AI service locally (with reload)
just start-api       # Start API gateway locally (with reload)

Environment Variables

Create a .env file in the project root:


# Database
DATABASE_URL=postgresql+asyncpg://dermadetect:password@localhost:5432/dermadetect
 
# AI Service
AI_SERVICE_URL=http://localhost:8080
 
# Authentication
JWT_SECRET=your-secret-key-change-in-production
 
# Cloud Storage (optional)
AZURE_CONN_STRING=your-azure-connection-string
GCS_BUCKET=your-gcs-bucket

Next Steps

📖 Read the Architecture guide to understand the system
🔧 Explore the API Reference for available endpoints
🚀 Learn about Deployment strategies

Troubleshooting

Port Already in Use

If ports 8000 or 8080 are already in use:


# Find and kill process on port 8000
lsof -ti:8000 | xargs kill -9
 
# Or change ports in docker-compose.yml

Database Connection Issues


# Check PostgreSQL is running
docker compose ps postgres
 
# View database logs
just logs-service postgres
 
# Reset database
just down
just up

Python Version Issues

Ensure you’re using Python 3.13:


python --version  # Should show 3.13.x
 
# Or use uv to manage Python versions
uv python install 3.13

Getting Help

📖 Check the documentation
🐛 Open an issue on GitHub
💬 Ask in team chat