Architecture Overview

Ralph is built on Django 4.2 and follows a modular architecture designed for managing assets, data centers, and configuration data. This guide explains the core architectural patterns and module organization.

Core Principles

Fat Models, Thin Views

Ralph’s architecture emphasizes business logic in Django models:

Models contain operational logic and data validation
Django Admin generates user interfaces automatically
Views primarily handle request/response without complex business logic

This approach prioritizes simplicity and leverages Django’s built-in admin capabilities for rapid development.

Modular Design

Ralph is organized into self-contained Django apps, each responsible for a specific domain:

src/ralph/
├── assets/              # Asset lifecycle management
├── data_center/         # Data center infrastructure
├── back_office/         # Office assets & equipment
├── licences/            # Software & hardware licenses
├── networks/            # IP address & network management
├── dhcp/                # DHCP configuration
├── dns/                 # DNS records
├── domains/             # Domain registration
├── ssl_certificates/    # SSL/TLS certificate tracking
├── sim_cards/           # SIM card inventory
├── access_cards/        # Physical access cards
├── supports/            # Support contracts
├── operations/          # Operational workflows
├── deployment/          # Asset deployment
├── data_importer/       # Bulk data import
├── reports/             # Reporting engine
└── dashboards/          # Custom dashboards

Technology Stack

Backend Framework

Django 4.2 - The foundation

Python 3.10 required (>=3.10.0, <3.11)
Django ORM for database abstraction
Django Admin for UI generation
Django REST Framework (3.15.0) for API

Key Dependencies

From pyproject.toml:

# Core Framework
django~=4.2.0
djangorestframework==3.15.0

# Database Support
mysqlclient~=2.0.1              # MySQL connector
psycopg[binary,pool]>=3.2.10   # PostgreSQL connector

# Caching & Background Jobs
django-redis==5.0.0
redis~=4.0
django-rq==2.8.0
rq==1.16.2

# Data Management
django-import-export~=4.0       # CSV/Excel import/export
django-reversion~=4.0.2         # Model versioning
django-mptt==0.14               # Hierarchical data

# API & Serialization
drf-nested-routers==0.92.5
djangorestframework_xml==2.0.0

# Utilities
django-filter==25.1             # API filtering
django-taggit                   # Tagging system
django-money==3.4.1             # Currency support

Frontend Stack

Node.js (v8.10.0 - v11.7.0)
npm for dependency management
Gulp for asset compilation
Custom JavaScript for admin enhancements

Infrastructure Services

MySQL 5.7 or PostgreSQL 14+ - Primary database
Redis 4.0+ - Caching and job queues
inkpy - Custom background job processor

Model Architecture

BaseObject Pattern

Most Ralph models inherit from BaseObject, which provides common functionality:

src/ralph/assets/models/base.py

class BaseObject(
    Polymorphic,
    TaggableMixin,
    PermByFieldMixin,
    TimeStampMixin,
    WithCustomFieldsMixin,
    models.Model,
    metaclass=BaseObjectMeta,
):
    """Base object mixin."""
    parent = models.ForeignKey(
        "self",
        null=True,
        blank=True,
        related_name="children",
        on_delete=models.SET_NULL,
    )
    remarks = models.TextField(blank=True)
    service_env = models.ForeignKey(
        "ServiceEnvironment", 
        null=True, 
        blank=True, 
        on_delete=models.PROTECT
    )
    configuration_path = models.ForeignKey(
        "ConfigurationClass",
        null=True,
        blank=True,
        on_delete=models.SET_NULL
    )
    attachments = GenericRelation(AttachmentItem)

Key Mixins

Mixin	Purpose	Provides
`Polymorphic`	Model inheritance	Content type tracking, polymorphic queries
`TaggableMixin`	Tagging support	Tag field and manager
`PermByFieldMixin`	Field-level permissions	Granular access control
`TimeStampMixin`	Automatic timestamps	`created`, `modified` fields
`WithCustomFieldsMixin`	Custom fields	User-defined fields per model
`TransitionWorkflowBase`	State machines	Workflow transitions

Polymorphic Models

Ralph uses polymorphic inheritance for asset types:

# All these inherit from BaseObject
DataCenterAsset    # Physical servers, network devices
BackOfficeAsset    # Laptops, monitors, peripherals
CloudHost          # Cloud instances
VirtualServer      # Virtual machines

This allows:

Unified queries across asset types
Type-specific fields and methods
Shared relationships (e.g., licenses, supports)

Module Structure

Each Django app follows a consistent structure:

assets/
├── __init__.py
├── apps.py              # App configuration
├── models/              # Domain models (split by concern)
│   ├── __init__.py
│   ├── base.py          # BaseObject and mixins
│   ├── assets.py        # Asset-specific models
│   ├── components.py    # Hardware components
│   └── configuration.py # Configuration management
├── admin.py             # Django admin configuration
├── api/                 # REST API endpoints
│   ├── serializers.py   # API serializers
│   └── views.py         # API viewsets
├── forms.py             # Custom forms
├── filters.py           # Query filters
├── views.py             # Web views
├── signals.py           # Signal handlers
├── subscribers.py       # Event subscribers
├── migrations/          # Database migrations
├── templates/           # HTML templates
└── tests/               # Unit and integration tests

API Architecture

Django REST Framework

Ralph exposes a comprehensive REST API:

# Typical API endpoint structure
from rest_framework import viewsets
from ralph.lib.mixins.api import (
    ChoiceFieldWithFullInfoSerializer,
    PermissionsForObjectMixin,
)

class DataCenterAssetViewSet(
    PermissionsForObjectMixin,
    viewsets.ModelViewSet
):
    queryset = DataCenterAsset.objects.all()
    serializer_class = DataCenterAssetSerializer
    filter_backends = [DjangoFilterBackend, OrderingFilter]
    filterset_class = DataCenterAssetFilter

Nested Routers

Related resources use nested routing:

/api/data-center-assets/
/api/data-center-assets/{id}/
/api/data-center-assets/{id}/components/
/api/data-center-assets/{id}/licenses/

Workflow System

Transitions

Ralph implements state machine workflows for asset lifecycle:

from ralph.lib.transitions.decorators import transition_action
from ralph.lib.transitions.models import Transition

class Asset(BaseObject):
    status = models.CharField(choices=AssetStatus.choices)
    
    @transition_action(
        form_fields={'remarks': {'required': True}}
    )
    def deploy(self, **kwargs):
        """Transition from 'new' to 'deployed'"""
        self.status = AssetStatus.DEPLOYED
        self.save()

Transitions support:

Custom validation
Dynamic forms
Audit logging
Email notifications

Data Import/Export

Import Engine

The data_importer module provides:

CSV/Excel file parsing
Field mapping
Validation and error reporting
Bulk create/update operations

Export Formats

Using django-import-export:

CSV
Excel (XLSX)
ODF (Open Document Format)
JSON
XML

Permission System

Field-Level Permissions

Ralph supports granular permissions:

class DataCenterAsset(BaseObject):
    class Meta:
        permissions = [
            ('view_datacenterasset', 'Can view data center asset'),
            ('change_datacenterasset', 'Can change data center asset'),
        ]

Permission Mixins

PermissionsForObjectMixin - Object-level API permissions
PermByFieldMixin - Field-level read/write control

Background Jobs

Django RQ

Ralph uses Redis Queue for asynchronous tasks:

from django_rq import job

@job
def process_network_scan(scan_id):
    """Background task for network discovery"""
    scan = NetworkScan.objects.get(id=scan_id)
    scan.execute()

inkpy Service

The inkpy container runs background workers:

Network discovery jobs
Report generation
Data synchronization
Email notifications

Configuration Management

Settings Structure

settings/
├── __init__.py
├── base.py          # Common settings
├── dev.py           # Development overrides
├── test.py          # Testing configuration
├── prod.py          # Production settings
└── local.template   # Local development template

Environment-Based Configuration

Settings support environment variables:

src/ralph/settings/local.template

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": os.environ.get("DATABASE_NAME", "ralph_ng"),
        "USER": os.environ.get("DATABASE_USER", "ralph_ng"),
        "PASSWORD": os.environ.get("DATABASE_PASSWORD", "ralph_ng"),
        "HOST": os.environ.get("DATABASE_HOST", "127.0.0.1"),
    }
}

Main Application Modules

Assets Module

Manages physical and virtual assets:

Asset lifecycle tracking
Component management
Purchase orders
Depreciation calculations
Asset assignment to users

Data Center Module

Data center infrastructure management:

Racks and rack units
Network devices
Servers and hardware
Power and network connections
DC visualization

Networks Module

IP address and network management:

IP address allocation
Network ranges
DNS records
DHCP configuration

Licenses Module

Software and hardware license tracking:

License assignment
Expiration monitoring
Compliance reporting

Database Design

Supported Databases

MySQL 5.7 - Default, widely tested
PostgreSQL 14+ - Alternative, full feature support

Character Sets

MySQL configuration requires UTF-8:

mysqld --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci

Migrations

Django migrations are stored per-app:

ralph/assets/migrations/
ralph/data_center/migrations/

Run migrations:

ralph migrate

Testing Architecture

Test Organization

Tests are organized by module:

assets/tests/
├── __init__.py
├── test_models.py
├── test_api.py
├── test_admin.py
└── factories.py

Test Dependencies

From pyproject.toml:

[dependency-groups]
test = [
  "coverage",
  "ddt",                          # Data-driven tests
  "factory-boy==3.2.1",           # Test fixtures
  "mock==4.0.2",
]

Running Tests

# All tests
test_ralph test

# Specific app
test_ralph test ralph.assets

# With coverage
coverage run $(which test_ralph) test
coverage report

Development Tools

Debugging

Development dependencies include:

django-debug-toolbar - SQL query analysis
django-silk - Performance profiling
ipdb - Interactive debugger
ipython - Enhanced Python shell

Code Quality

ruff - Fast Python linter (replaces flake8)
toml-sort - TOML file formatting

# Run linter
make checks

# Or directly
ruff check src

Extension Points

Custom Fields

Add user-defined fields to any model:

from ralph.lib.custom_fields.models import WithCustomFieldsMixin

class MyModel(WithCustomFieldsMixin, models.Model):
    # Custom fields are automatically available
    pass

Hooks System

Extend functionality using Django signals:

from django.db.models.signals import post_save
from django.dispatch import receiver

@receiver(post_save, sender=DataCenterAsset)
def on_asset_saved(sender, instance, created, **kwargs):
    if created:
        # Custom logic on asset creation
        pass

Admin Customization

Extend Django admin:

from ralph.admin import RalphAdmin

class CustomAssetAdmin(RalphAdmin):
    list_display = ['name', 'barcode', 'status']
    list_filter = ['status', 'service_env']
    search_fields = ['barcode', 'sn']

Performance Considerations

Caching Strategy

Redis for session storage
Query result caching for expensive operations
Static file caching via nginx

Query Optimization

Use select_related() for foreign keys
Use prefetch_related() for many-to-many
Index frequently queried fields

Database Connection Pooling

PostgreSQL uses connection pooling:

"OPTIONS": {
    "pool": True,  # psycopg3 pooling
}

Next Steps

Setup Guide

Set up your development environment

API Reference

Explore the REST API

Contributing

Learn how to contribute

Custom Fields

Extend models with custom fields

Getting Started

Extending Ralph

Reference

Contributing

​Core Principles

​Fat Models, Thin Views

​Modular Design

​Technology Stack

​Backend Framework

​Key Dependencies

​Frontend Stack

​Infrastructure Services

​Model Architecture

​BaseObject Pattern

​Key Mixins

​Polymorphic Models

​Module Structure

​API Architecture

​Django REST Framework

​Nested Routers

​Workflow System

​Transitions

​Data Import/Export

​Import Engine

​Export Formats

​Permission System

​Field-Level Permissions

​Permission Mixins

​Background Jobs

​Django RQ

​inkpy Service

​Configuration Management

​Settings Structure

​Environment-Based Configuration

​Main Application Modules

​Assets Module

​Data Center Module

​Networks Module

​Licenses Module

​Database Design

​Supported Databases

​Character Sets

​Migrations

​Testing Architecture

​Test Organization

​Test Dependencies

​Running Tests

​Development Tools

​Debugging

​Code Quality

​Extension Points

​Custom Fields

​Hooks System

​Admin Customization

​Performance Considerations

​Caching Strategy

​Query Optimization

​Database Connection Pooling

​Next Steps

Setup Guide

API Reference

Contributing

Custom Fields

Build docs developers (and LLMs) love

Core Principles

Fat Models, Thin Views

Modular Design

Technology Stack

Backend Framework

Key Dependencies

Frontend Stack

Infrastructure Services

Model Architecture

BaseObject Pattern

Key Mixins

Polymorphic Models

Module Structure

API Architecture

Django REST Framework

Nested Routers

Workflow System

Transitions

Data Import/Export

Import Engine

Export Formats

Permission System

Field-Level Permissions

Permission Mixins

Background Jobs

Django RQ

inkpy Service

Configuration Management

Settings Structure

Environment-Based Configuration

Main Application Modules

Assets Module

Data Center Module

Networks Module

Licenses Module

Database Design

Supported Databases

Character Sets

Migrations

Testing Architecture

Test Organization

Test Dependencies

Running Tests

Development Tools

Debugging

Code Quality

Extension Points

Custom Fields

Hooks System

Admin Customization

Performance Considerations

Caching Strategy

Query Optimization

Database Connection Pooling

Next Steps