DentalPin Docs

Appearance

0001 — Modular plugin architecture ​

  • Status: accepted
  • Date: 2026-04-27
  • Tags: modules, architecture

Context ​

DentalPin serves a wide spectrum of dental clinics: solo practices, group clinics, multi-specialty centers, and country-specific compliance regimes (e.g. Veri*Factu in Spain). A monolithic codebase forces every clinic to carry every feature, makes country-specific compliance code mix with generic clinical logic, and turns every uninstall into a risky migration.

The product also relies on an open-source community to extend it (BSL 1.1 → Apache 2.0). Third-party developers need a clear, stable contract for plugging in features without forking the core.

Decision ​

Build the system as independent modules under backend/app/modules/<name>/, discovered via pyproject.toml entry points (dentalpin.modules), each owning its router, models, migrations, events, permissions, and frontend layer. Inter-module communication is contract-driven:

  • Direct service-to-service imports across modules are forbidden unless the target is in manifest.depends.
  • The preferred mechanism for cross-module reactions is the event bus (see ADR 0003).
  • Cross-module FKs are allowed only against modules in depends; CI rejects migrations otherwise.
  • Permissions are namespaced by the registry: a module returns resource.action, the registry prefixes with the module name (see ADR 0005).

Each module declares its identity, dependencies, install policy, and role-permission seeds in a single manifest dict on the module class.

Consequences ​

Good ​

  • Clinics install only what they need; uninstall is a real, tested operation (see ADR 0002 and backend/tests/test_uninstall_roundtrip.py).
  • Country-specific compliance lives in its own module (verifactu) without polluting billing.
  • Third parties can ship modules as separate Python packages with their own entry point.
  • Each module is a small, agent-friendly unit of work — agents can be briefed on one module without reading the whole codebase.

Bad / accepted trade-offs ​

  • More boilerplate per feature (manifest, branch label, frontend layer, events).
  • Event-driven cross-module flows are harder to debug than direct function calls; we accept this in exchange for isolation.
  • Refactors that span multiple modules need to respect the contract — no drive-by reorganizations.

Alternatives considered ​

  • Single monolithic FastAPI app. Rejected: no clean uninstall, no third-party extensibility, country-specific code drifts everywhere.
  • Microservices. Rejected: ops overhead is wrong for a clinic-scale product; transactional integrity inside a clinic matters more than service-level horizontal scaling.

How to verify the rule still holds ​

  • backend/tests/test_module_manifest.py
  • backend/tests/test_module_manifests_consistency.py
  • backend/tests/test_manifest_validator.py
  • CI job manifest-consistency (.github/workflows/ci.yml)

References ​

  • docs/technical/creating-modules.md — module-author contract
  • backend/app/core/plugins/base.py:21 — BaseModule
  • backend/app/core/plugins/manifest.py — manifest schema
  • backend/app/core/plugins/loader.py:159 — discover_modules
  • backend/app/core/plugins/registry.py:12 — ModuleRegistry
  • Root CLAUDE.md — "Modular architecture" section