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

cp .env.example .env
source .env
uv run --extra dev manage.py migrate
uv run --extra dev manage.py runserver

Database Operations

uv run --extra dev manage.py migrate
uv run --extra dev manage.py makemigrations
uv run --extra dev manage.py createsuperuser

Testing

# 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

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