Inside a Horilla CRM App: registration.py, menu.py, and What AppLauncher Actually Loads

horilla_crm/leads/
├── apps.py              # AppLauncher config
├── registration.py      # Feature + platform hooks  ← critical
├── menu.py              # Sidebar / FAB / settings menus
├── signals.py           # Cross-module event handlers
├── dashboard.py         # Dashboard chart generators
├── models/              # HorillaCoreModel subclasses
├── views/               # horilla_generics CBVs
├── forms.py             # HorillaModelForm / HorillaMultiStepForm
├── filters.py           # HorillaFilterSet
├── urls.py              # Namespaced routes (app_name = "leads")
├── api/                 # DRF serializers + router
├── celery_schedules.py  # Beat tasks (merged by AppLauncher)
└── templates/           # HTMX partials

from horilla.apps import AppLauncher
from horilla.utils.translation import gettext_lazy as _


class LeadsConfig(AppLauncher):
    default = True
    name = "horilla_crm.leads"
    verbose_name = _("Leads")

    url_prefix = "crm/leads/"
    url_module = "horilla_crm.leads.urls"
    url_namespace = "leads"

    auto_import_modules = [
        "registration",
        "signals",
        "menu",
        "dashboard",
    ]

    celery_schedule_module = "celery_schedules"
    celery_schedule_variable = "HORILLA_CRM_BEAT_SCHEDULE"

    def get_api_paths(self):
        return [{
            "pattern": "crm/leads/",
            "view_or_include": "horilla_crm.leads.api.urls",
            "name": "horilla_crm_leads_api",
            "namespace": "horilla_crm_leads",
        }]

from horilla.registry.feature import register_model_for_feature
from horilla.contrib.cadences.registration import register_cadence_tab

register_model_for_feature(
    app_label="leads",
    model_name="LeadStatus",
    features=["import_data", "export_data", "global_search"],
)

register_model_for_feature(
    app_label="leads",
    model_name="Lead",
    all=True,
    features=[
        "duplicate_models",
        "approval_models",
        "reviews_models",
        "workflow_models",
        "scoring",
    ],
)

register_cadence_tab(
    app_label="leads",
    model_name="Lead",
    url_prefix="lead-cadences-tab/<int:pk>/",
    url_name="lead_cadences_tab",
)

from horilla.urls import reverse_lazy
from horilla.menu import floating_menu
from .models import Lead

@floating_menu.register
class LeadFloating:
    title = Lead()._meta.verbose_name
    url = reverse_lazy("leads:leads_create")
    icon = "/assets/icons/leads.svg"
    items = {
        "hx-target": "#modalBox",
        "hx-swap": "innerHTML",
        "onclick": "openModal()",
        "perm": ["leads.add_lead"],
    }

from horilla.menu import (
    main_section_menu,
    sub_section_menu,
    MAIN_CONTENT_HX_ATTRS,
)
from horilla.utils.translation import gettext_lazy as _

@main_section_menu.register
class SalesSection:
    section = "sales"
    name = _("Sales")
    icon = "/assets/icons/sales.svg"
    position = 1

@sub_section_menu.register
class LeadSubSection:
    section = "sales"
    app_label = "leads"
    position = 1
    verbose_name = _("Leads")
    icon = "/assets/icons/leads.svg"
    url = reverse_lazy("leads:leads_view")
    attrs = MAIN_CONTENT_HX_ATTRS
    perm = ["leads.view_lead", "leads.view_own_lead"]

MAIN_CONTENT_HX_ATTRS = {
    "hx-boost": "true",
    "hx-target": "#mainContent",
    "hx-select": "#mainContent",
    "hx-swap": "outerHTML",
}

from django.dispatch import receiver
from horilla.contrib.core.signals import company_created, company_currency_changed
from horilla.urls import reverse_lazy
from horilla.shortcuts import render

@receiver(company_created)
def handle_company_created(sender, instance, request, view, is_new, **kwargs):
    if is_new:
        url = reverse_lazy("leads:load_lead_stages", kwargs={"company_id": instance.id})
        return render(
            request,
            "lead_status/reload_and_load_url_script.html",
            {"load_url": str(url)},
        )
    return None

@receiver(company_currency_changed)
def update_crm_on_currency_change(sender, **kwargs):
    company = kwargs.get("company")
    conversion_rate = kwargs.get("conversion_rate")
    leads_to_update = []
    for lead in Lead.objects.filter(company=company).only("id", "annual_revenue"):
        if lead.annual_revenue is not None:
            # apply conversion_rate, collect for bulk_update
            ...

from horilla.db.models import Count
from horilla.contrib.dashboard.utils import DefaultDashboardGenerator
from .models import Lead

def create_lead_source_charts(self, queryset, model_info):
    data = queryset.values("lead_source").annotate(count=Count("id")).order_by("-count")
    if not data.exists():
        return None
    labels = [item["lead_source"] or "Unknown" for item in data]
    values = [item["count"] for item in data]
    return {
        "title": "Leads by Source",
        "type": "funnel",
        "data": {"labels": labels, "data": values, "urls": urls},
    }

DefaultDashboardGenerator.extra_models.append({
    "model": Lead,
    "name": "Leads",
    "kpi_func": lead_kpi_cards,
    "chart_func": [create_lead_source_charts, create_lead_charts_by_stage],
    "table_func": [lead_convert_table_func, lead_open_pipeline_table_func],
})

from horilla.urls import path
from horilla_crm.leads import views

app_name = "leads"

urlpatterns = [
    path("leads-view/", views.LeadView.as_view(), name="leads_view"),
    path("leads-list/", views.LeadListView.as_view(), name="leads_list"),
    path("leads-kanban/", views.LeadKanbanView.as_view(), name="leads_kanban"),
    path("leads-detail/<int:pk>/", views.LeadDetailView.as_view(), name="leads_detail"),
]

flowchart TD
    A[Django loads INSTALLED_APPS] --> B[LeadsConfig.ready]
    B --> C[Register /crm/leads/ URLs]
    B --> D[import registration.py]
    B --> E[import menu.py]
    B --> F[import signals.py]
    B --> G[import dashboard.py]
    D --> H[FEATURE_REGISTRY populated]
    E --> I[Menu decorators collected]
    F --> J[Signal handlers connected]
    G --> K[Dashboard generators registered]

python manage.py start_horilla_app my_module