website/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Django website for servala.com, built with Python 3.13+ using uv for dependency management. The project structure follows Django conventions with a main `hub` application containing multiple services.

## Development Commands

### Local Development Setup
```bash
cp .env.example .env
source .env
uv run --extra dev manage.py migrate
uv run --extra dev manage.py runserver
```

### Database Operations
```bash
uv run --extra dev manage.py migrate
uv run --extra dev manage.py makemigrations
uv run --extra dev manage.py createsuperuser
```

### Testing
```bash
# Run all tests
uv run --extra dev manage.py test

# Run specific pricing tests (comprehensive suite available)
./run_pricing_tests.sh

# Run specific test modules
uv run --extra dev manage.py test hub.services.tests.test_pricing --verbosity=2
uv run --extra dev manage.py test hub.services.tests.test_pricing_edge_cases --verbosity=2
uv run --extra dev manage.py test hub.services.tests.test_pricing_integration --verbosity=2
```

### Asset Management
```bash
uv run --extra dev manage.py build_assets
uv run --extra dev manage.py collectstatic
```

## Architecture Overview

### Core Django App Structure
- `hub/` - Main Django application
  - `services/` - Core business logic with multiple domains:
    - `models/` - Database models organized by domain (articles, pricing, providers, services, etc.)
    - `views/` - View logic organized by feature
    - `forms/` - Form classes for user input
    - `admin/` - Django admin customizations
    - `tests/` - Comprehensive test suite, especially for pricing logic
  - `broker/` - Separate app for broker-related functionality
  - `middleware.py` - Custom middleware
  - `settings.py` - Django configuration using environs for environment variables

### Key Features
- **Pricing Engine**: Complex pricing calculations with multiple models (ComputePlan, StoragePlan, etc.)
- **Content Management**: Articles, services, providers with image library support
- **Lead Generation**: Contact forms and lead management
- **Partner System**: Cloud providers and consulting partners
- **Price Calculator**: Interactive frontend calculator with ROI calculations

### Frontend Assets
- Static files in `hub/services/static/`
- JavaScript organized by feature:
  - `price-calculator/` - Modular price calculator components
  - `roi-calculator/` - Modular ROI calculator with separate concerns (core, UI, charts, exports)
- CSS using Bootstrap 5 with custom styling
- Chart.js for data visualization

### Database
- Uses Django ORM with extensive migrations in `hub/services/migrations/`
- SQLite for development and production (`db.sqlite3`)
- Media files stored in `media/` with organized subdirectories

### Deployment
- Docker specific code is in the folder docker/
- Kubernetes deployment specific files in deployment/
- GitLab CI is used as the main CI/CD system
- Forgejo Actions is the secondary CI/CD system

## Development Notes

### Environment Configuration
- Uses `environs` library for environment variable management
- Requires `.env` file for local development (copy from `.env.example`)
- Key settings: `SECRET_KEY`, `DEBUG`, `ALLOWED_HOSTS`

### Testing Strategy
- Extensive pricing test suite with edge cases and integration tests
- Use `--keepdb` flag for faster test runs during development
- Dedicated test runner script for pricing functionality

### Asset Pipeline
- Django Compressor for CSS/JS optimization
- Static files collection required for production
- Custom management commands for asset building

### Image Management
- Comprehensive image library system with SVG support
- Organized media directories for different content types
- Custom template tags for image handling

### Django specifics
- Use function-based views and follow the Django conventions for naming and structuring views
- Templates use the Django template language

### Claude Code specific
- Use context7 to get up-to-date documentation about Bootstrap, Python and Django