Skip to content

TODOS — DentalPin

The open standard for dental clinic management.


1. VISION AND PRINCIPLES

What is DentalPin

DentalPin is open source dental clinic management software designed to be:

  • Modular — Every feature is a self-contained module
  • API-First — Everything is accessible via REST API
  • Multi-tenant — Built for clinic isolation from day one
  • Extensible — Third parties can build integrations and modules

License: BSL 1.1

  • Free to use for clinics (self-hosted or cloud)
  • Contributions welcome and encouraged
  • Prohibited to host as a competing commercial SaaS
  • Converts to Apache 2.0 after 4 years

2. PRIORITIES

Priority Tags

TagMeaningTimeline
🔴 P0Blocks first clinic in productionImmediate
🟠 P1Required for 10 clinics + legal compliance3-6 months
🟡 P2Enables ecosystem growth6-12 months
🟢 P3Advanced features, long term12-24 months
DeadlineRequirementImpact
January 2027Verifactu mandatory for companiesWithout this, no Spanish SL can legally use the software
July 2027Verifactu mandatory for freelancersFull Spanish market coverage

3. PLATFORM LAYERS

3.1 Core Platform (BSL 1.1)

What is NOT a module. The foundation everything else builds on.

ComponentStatusDescription
Plugin SystemAuto-discovery, dependency resolution
Auth + RBACJWT, 5 roles, wildcard permissions
Event BusPub/sub for module communication
Multi-tenancyClinic isolation, membership
REST APIOpenAPI, versioned

3.2 First-Party Modules (BSL 1.1)

Included by default. Functionality every clinic needs.

ModuleStatusFunction
clinical⚠️ PartialPatients, appointments (basic)
odontogramInteractive FDI dental chart
catalogTreatment catalog with VAT types
budgets✅ P0Budgets/quotes + PDF
billing✅ P0Invoicing
patient-record⚠️ PartialPhase 1 ✅, Phase 2 ⚠️ (documents), Phase 3-4 pending
clinical-notes🟠 P1Clinical evolution (SOAP)
imaging🟠 P1Clinical images and X-rays
booking🟠 P1Online booking
communications🟠 P1Reminders, notifications

Complete Patient Record 🔴 P0

The current patient record is basic. Implementation divided into 4 phases:


Phase 1: Core Patient Data + Medical History + Alerts ✅

Extended clinical module with:

  • Patient demographics (gender, national_id, profession, workplace, address)
  • Emergency contact with legal guardian support
  • Medical history JSONB (allergies, medications, systemic diseases, surgical history, special conditions)
  • Patient alerts computed from medical history
  • Patient timeline populated via event handlers
  • Sidebar + tabs UI layout with quick info and alerts banner

Phase 2: Documents + File Storage ⚠️ Partial

Scope: New media module with storage abstraction. Patient documents functionality.

Architecture Decisions:

  • Separate media module (reusable for images, X-rays, attachments)
  • StorageBackend protocol: LocalStorage (MVP), S3Storage (future)
  • File metadata in DB, actual files in configured storage
  • Document types: consent, id_scan, insurance, report, referral, other

Backend Tasks:

TaskStatusDescription
Create media moduleBaseModule subclass with dependencies: ["clinical"]
StorageBackend protocolupload, download, delete, get_url methods
LocalStorage implementationDocker volume mount, path-based storage
Document modelpatient_id, document_type, filename, storage_path, mime_type, file_size, title, description, metadata (JSONB), uploaded_by
Upload endpointPOST /patients/{id}/documents with multipart form, validation (size, type)
List/Get/Delete endpointsStandard CRUD with permission checks
Download endpointStreaming response with correct content-type
Permissionsmedia.documents.read/write
File validationMax size (10MB default), allowed MIME types
Alembic migrationo5p6q7r8s9t0_add_documents_table.py

Frontend Tasks:

TaskStatusDescription
useDocuments composablefetchDocuments, uploadDocument, downloadDocument, deleteDocument, updateDocument
DocumentUpload componentDrag-drop zone, progress indicator, type selector
DocumentGallery componentGrid view, type filter, pagination
DocumentCard componentPDF/image icon, title, type badge, download/edit/delete actions
DocumentViewer component🔴PDF inline viewer, image lightbox (not implemented)
Add Documents tab to patientSeparate Documents tab in patient detail
i18n translationsSpanish and English complete

Document Types:

TypeDescriptionIcon
consentSigned consent formsfile-signature
id_scanDNI/NIE/Passport scanid-card
insuranceInsurance cardshield
reportExternal medical reportsfile-text
referralReferral lettersfile-output
otherOther documentsfile

Storage Configuration:

python
# backend/app/core/config.py
STORAGE_BACKEND: str = "local"  # local | s3
STORAGE_LOCAL_PATH: str = "/app/storage"
STORAGE_MAX_FILE_SIZE: int = 10 * 1024 * 1024  # 10MB
STORAGE_ALLOWED_TYPES: list = ["application/pdf", "image/jpeg", "image/png"]

Files Created/Modified:

  • backend/app/modules/media/ — New module (models, router, schemas, service, storage)
  • backend/alembic/versions/o5p6q7r8s9t0_add_documents_table.py — Migration
  • backend/tests/test_media.py — Backend tests
  • frontend/app/components/media/ — DocumentCard, DocumentGallery, DocumentUpload
  • frontend/app/composables/useDocuments.ts — Documents composable
  • frontend/app/config/permissions.ts — Added documents permissions
  • frontend/i18n/locales/{en,es}.json — Translations

Scope: Extend media module with clinical image organization and treatment linkage.

Architecture Decisions:

  • ClinicalImage extends Document with category and treatment association
  • Thumbnail generation on upload (pillow/PIL)
  • Before/after pairing via paired_image_id
  • Categories organized by clinical use

Backend Tasks:

TaskDescription
ClinicalImage modelExtends Document: image_category, associated_treatment_id (FK ToothTreatment), is_before_image, paired_image_id, thumbnail_path
Thumbnail serviceGenerate thumbnails on upload (300x300), store alongside original
Category endpointsGET /patients/{id}/clinical-images?category=intraoral_frontal
Before/after pairingLink images, create comparison metadata
Treatment linkageAssociate images with specific tooth treatments

Frontend Tasks:

TaskDescription
useClinicalImages composablefetchImages, uploadImage, categorize, pair
ImageGallery componentMasonry grid, category tabs, date grouping
ImageViewer componentLightbox with zoom, pan, navigation
ImageCompare componentSide-by-side slider for before/after
ImageUpload componentCategory selector, treatment selector, before/after toggle
Add Images tab to patientNew tab in patient detail

Image Categories:

CategoryCodeDescription
Intraoral Frontalintraoral_frontalFront view of teeth closed
Intraoral Leftintraoral_leftLeft lateral view
Intraoral Rightintraoral_rightRight lateral view
Intraoral Occlusal Upperintraoral_occlusal_upperMirror view upper arch
Intraoral Occlusal Lowerintraoral_occlusal_lowerMirror view lower arch
Extraoral Frontalextraoral_frontalFace front view
Extraoral Smileextraoral_smileSmile view
Extraoral Profile Leftextraoral_profile_leftLeft profile
Extraoral Profile Rightextraoral_profile_rightRight profile
Treatment Specifictreatment_specificAssociated with specific treatment

Phase 4: X-rays and DICOM Foundation 🟡 P2

Scope: X-ray image support with DICOM awareness (no full viewer in this phase).

Architecture Decisions:

  • Xray model extends ClinicalImage with radiography-specific fields
  • DICOM metadata extraction (pydicom library)
  • Convert DICOM to web-viewable format (JPEG preview)
  • Store original DICOM for future viewer integration
  • Temporal comparison via date slider

Backend Tasks:

TaskDescription
Xray modelExtends ClinicalImage: xray_type, tooth_numbers[], acquisition_date, dicom_metadata (JSONB), is_dicom
DICOM serviceExtract metadata (study date, modality, patient info), convert to JPEG preview
Temporal comparison endpointGET /patients/{id}/xrays/compare?tooth=11&dates=2024-01,2025-01
X-ray type classificationpanoramic, periapical, bite_wing, cbct, cephalometric

Frontend Tasks:

TaskDescription
useXrays composablefetchXrays, uploadXray, compare
XrayGallery componentGrid with type filter, tooth filter
XrayViewer componentZoom, contrast adjustment, measurement tools (basic)
XrayCompare componentTemporal slider, side-by-side, overlay
XrayUpload componentType selector, tooth selector, date picker
Add X-rays section to Images tabSub-tab or separate section

X-ray Types:

TypeCodeDescription
PanoramicpanoramicFull mouth panoramic
PeriapicalperiapicalSingle tooth detailed view
Bite Wingbite_wingInterproximal view
CBCTcbct3D cone beam (metadata only, no 3D viewer)
CephalometriccephalometricLateral skull view

DICOM Metadata to Extract:

TagFieldUse
(0008,0020)Study Dateacquisition_date
(0008,0060)Modalityxray_type hint
(0010,0010)Patient Namevalidation
(0018,0015)Body Partclassification
(0028,0010)Rowsimage dimensions
(0028,0011)Columnsimage dimensions

Future Integration Points (not in Phase 4):

  • OHIF Viewer integration for CBCT
  • cornerstone.js for web DICOM viewing
  • AI-assisted pathology detection
  • Measurement and annotation persistence

Treatment Catalog (catalog) ✅ Implemented

FeatureStatusDescription
Internal codesPer-clinic internal treatment codes
Multi-languageLocalized names and descriptions (i18n)
CategoriesHierarchical categories with icons
PricingDefault price + cost price tracking
DurationDefault times for scheduling integration
VATConfigurable VAT types per clinic
Odontogram mappingLink treatments to odontogram visualization
Treatment scopeSurface vs whole tooth classification
Multi-code🟠 P1Official nomenclatures (RCOE, CCAM, CDT/ADA)
Price lists🟠 P1Multiple rates (private, insured, promotional)
Packages🟡 P2Combined treatment templates
Materials🟠 P1Inventory linkage
Import/Export🟠 P1CSV import/export

Budgets (budgets) ✅ P0

FeatureDescription
Linked lines✅ Catalog + tooth/surface from odontogram
Discounts🔴 Per line and global
Workflow✅ Draft → Presented → Accepted → In progress → Completed
Partial acceptancePatient accepts some lines
Validity✅ Expiration period
PDF✅ With clinic branding
Digital signature🔴 E-signature for acceptance
Conversion🔴 Budget → Appointments → Invoices

Billing (billing) ✅ P0

FeatureDescription
From budget✅ Auto-populate from budget
Manual✅ Direct creation
Status✅ Draft → Issued → Paid → Partial → Cancelled/Credit note
Multi-tax✅ VAT exempt (healthcare) vs taxable (cosmetic)
Payments✅ Record payments (cash, card, transfer)
Verifactu-ready✅ Fields prepared (hash, QR)
PDF✅ With legal requirements
Series🟠 Configurable numbering

3.3 Community/Third-Party Modules

Opportunities for developers, equipment manufacturers, labs, and insurers.

Compliance (by country)

ModuleCountryDescription
verifactu-es🇪🇸 SpainHash chain, QR, AEAT submission
factur-x-fr🇫🇷 FranceFrench electronic invoicing
sdi-it🇮🇹 ItalySistema di Interscambio
furs-si🇸🇮 SloveniaFURS fiscalization

Clinical Integrations

ModuleTypeDescription
dicom-viewerRadiologyEmbedded DICOM viewer
lab-ordersLabsOrders to prosthetic labs
insurance-claimsInsuranceClaims processing
intraoral-captureHardwareIntraoral camera capture

Communications

ModuleDescription
sms-twilioTwilio SMS integration
whatsapp-businessWhatsApp Business API
email-sendgridSendGrid/Mailgun

Clinical Specialties

ModuleSpecialtyDescription
ortho-trackingOrthodonticsCephalometry, aligner tracking
perio-chartingPeriodonticsProbing, PSR/BPE
implant-planningImplantologyPlanning, implant registry
endo-workflowEndodonticsWorking length, file sequence

AI

ModuleDescription
imaging-aiAssisted pathology detection in X-rays
voice-dictationClinical note dictation
smart-schedulingML-based schedule optimization

4. OPPORTUNITIES FOR THIRD PARTIES

DentalPin is designed so the entire dental industry can build modules.

For Dental Equipment Manufacturers

Equipment TypeExample ManufacturersEvents to consume
Radiology/DICOMPlanmeca, Vatech, Carestreampatient.opened, treatment.planned
Intraoral camerasDentsply Sirona, Acteonappointment.started
CAD/CAMCEREC, 3Shapetreatment.completed
ChairsKaVo, A-decappointment.checked_in

Benefit: Your equipment integrates natively with the software clinics use 8h/day.

For Prosthetic Labs

ModuleFunction
lab-ordersSend cases from patient record
lab-trackingReal-time work status
digital-impressionsSTL file management
shade-managementColor communication

Benefit: Direct order channel from clinical workflow.

For Insurance Companies

ModuleFunction
insurance-coverageAutomatic pre-authorizations
insurance-billingDirect billing to insurer
coverage-calculatorCoverage simulation in budget
claims-statusReal-time claims tracking

Benefit: Reduced friction in authorizations and payments.

For Communication Companies

ModuleFunction
sms-remindersTwilio, MessageBird, Vonage
whatsapp-businessBidirectional communication
email-campaignsRecalls, dental marketing
review-managementPost-visit review requests

For Independent Developers

ModuleComplexityImpact
Translations (FR, PT, DE)LowHigh
Export ICS (Google Calendar)LowMedium
Dark modeLowMedium
Digital consentsMediumHigh
Orthodontics trackingHighNiche
Periodontics chartingHighNiche

5. ROADMAP BY PHASE

Phase 0: Foundation (Current) ✅

What's already built:

ComponentStatus
Backend FastAPI + SQLAlchemy
Frontend Nuxt 3 + Nuxt UI
Plugin system with auto-discovery
RBAC with 5 roles and wildcards
Multi-tenancy (clinic isolation)
Event bus
Clinical module (patients, appointments)
Odontogram module (FDI chart)
6 frontend pages, 18 components
Docker Compose deployment

Phase 1: Functional Clinic MVP 🔴 P0

Goal: A small clinic can operate day to day.

ModuleStatusKey Deliverables
patient-record🔴Complete record: anamnesis, alerts, documents
catalogTreatment catalog with VAT types, odontogram mapping
budgetsBudgets with complete workflow + PDF
billingBasic invoicing + PDF
imaging-basic🔴Basic clinical image gallery
AI Infrastructure🔴ToolRegistry, ContextProvider

Phase 2: Production 🟠 P1

Goal: Ready for 10 real clinics. Legal compliance.

ModuleKey DeliverablesDeadline
verifactu-esHash chain, QR, AEAT submissionJanuary 2027
bookingEmbeddable widget, standalone page
communicationsReminders SMS/email/WhatsApp
inventoryStock management, reorder alerts
data-importMigration from Gesden, Clinic Cloud, CSV
Multi-clinicClinic switcher, shared patients
PaymentsStripe, Redsys integration

Phase 3: Ecosystem 🟡 P2

Goal: Third parties build on the platform.

ComponentKey Deliverables
Marketplace v1Module browser, install/uninstall
Developer PortalSDK, docs, module templates
Partner ProgramPartner portal, certification
insuranceCoverage tables, claims
clinical-notesSOAP evolution, templates
prescriptionsPrescriptions with interactions
AI AssistantChat interface, task execution

Phase 4: Scale 🟢 P3

Goal: DentalPin is the industry standard.

ComponentKey Deliverables
Specialty modulesOrtho, perio, implants, endo
InternationalFR, PT, DE, IT locales + compliance
AI ClinicalDecision support, imaging analysis
VoiceDictation, voice commands
White-labelTheming for partners

6. SUCCESS METRICS

Adoption Metrics

MilestoneTargetValidation
First clinicMonth 31 clinic using daily
ValidationMonths 1-63-5 trusted clinics + feedback
Product-market fitMonth 620 clinics, churn <5%
ScaleMonth 12100 clinics
StandardMonth 241,000 clinics

Community Metrics

MetricMonth 6Month 12Month 24
GitHub Stars505002,000
External contributors31050
Third-party modules1520
Countries with deployments1310

7. GOOD FIRST ISSUES

Small, well-scoped features for new contributors.

Translations (no code)

  • [ ] i18n/locales/fr.json — French translation
  • [ ] i18n/locales/pt.json — Portuguese translation
  • [ ] i18n/locales/de.json — German translation

Frontend (low risk)

  • [ ] Keyboard shortcuts for common actions
  • [ ] Export appointment to ICS format (Google Calendar)
  • [ ] Print view for patient record
  • [ ] Skeleton loaders for all pages

Backend (low risk)

  • [ ] Improved seed data (more test cases)
  • [ ] Detailed health check endpoint (/health/detailed)
  • [ ] Configurable rate limiting

Documentation

  • [ ] Tutorial: "My first module in 30 minutes"
  • [ ] Video walkthrough of architecture
  • [ ] Updated architecture diagrams

Testing

  • [ ] E2E tests with Playwright for critical flows
  • [ ] Increase unit test coverage to 80%
  • [ ] Accessibility (a11y) tests

8. TECHNICAL DETAILS BY MODULE

Verifactu (verifactu-es) 🟠 P1

Legal deadline: January 2027 (companies), July 2027 (freelancers)

ComponentDescription
Hash chainSHA-256 chained from previous invoice
QR codeGeneration on each invoice
AEAT submissionReal-time or batched submission
CertificatesDigital signature management
Audit logImmutable events for auditing
Separate moduleNon-Spanish deployments don't load this

Extensible: The pattern works for Factur-X (FR), SDI (IT), etc.


Clinical Notes (clinical-notes) 🟠 P1

FeatureDescription
Rich textWith attachments (images, files)
TemplatesBy treatment type (endo, implant, etc.)
Quick vs structuredToggle by preference
Lock after signNot editable after finalization, only amendments
AI dictationVoice-to-text + auto-structuring
SearchableFull-text search across patients

Online Booking (booking) 🟠 P1

FeatureDescription
Embeddable widgetFor clinic website
Standalone pageWith clinic branding
Configurable slotsBy treatment type
New patient registrationDuring booking
ICS inviteConfirmation with calendar file
Anti-spamCaptcha, rate limiting

Data Import (data-import) 🟠 P1

Critical: Without migration, nobody switches software.

SourceFormat
GesdenSpecific export
Clinic CloudSpecific export
CS R4Specific export
GenericCSV/Excel mapping tool
FHIRFor interoperability
FeatureDescription
Mapping toolMap source fields → DentalPin
Dry-runPreview before commit
ValidationDetect errors and conflicts
RollbackAbility to undo

AI Infrastructure 🔴 P0

Tracked in issue #42. Phase 1 landed the core contract; Phase 2/3 extend the system with UX, a reference agent, and scheduling.

Phase 1 — Core Contract ✅ (shipped)

ComponentStatusDescription
ToolRegistryNamespaced registry, JSON Schema helper, single-chokepoint call()
BaseAgent + AgentContextAbstract base, mode enum, execution context
BaseModule.get_tools()Mandatory abstract on every module (all 13 stubbed)
BaseModule.get_agents()Default [], override to register agent classes
GuardrailsRate limits, blocked tools, require-approval patterns, auto-approval for DESTRUCTIVE / supervised-WRITE
Audit logagent_audit_logs table, every tool attempt recorded
Approval queue (backend)agent_approval_queue + service + endpoints
agents.* RBACagents.view/supervise/configure/manage permissions
Docsdocs/technical/creating-modules.md §12 "AI agent integration"

Phase 2 — UX + First Agent 🟠 P1

  • [ ] Frontend approval UI/approvals page, pending-count badge in navbar, approve/reject modal with notes field. Use ListRow + StatusBadge.
  • [ ] Reference Appointment Reminder Agent — standalone module at backend/app/modules/agents/reminder/. Add anthropic SDK to backend/requirements.txt. Demonstrates tool discovery, multi-turn tool loop, audit trail.
  • [ ] Cron / scheduling trigger — APScheduler in-process or external cron hitting POST /api/v1/agents/{id}/run. Decide when building the reminder agent.
  • [ ] Per-module tool retrofit — wrap existing service methods as Tools, module by module, as real agents need them. Start with agenda (appointments) + patients (search) since the reminder agent needs them.

Phase 3 — Hardening 🟡 P2

  • [ ] Per-clinic guardrail configuration UI (admin) — edit rate limits, blocked patterns, require-approval patterns from settings
  • [ ] AgentMemory production backends — Redis for short-term session memory, Postgres for long-term
  • [ ] LLM abstraction layer — optional, only if a second provider appears or cost tracking needs a central chokepoint
  • [ ] Distributed rate-limit store — replace in-process counters once DentalPin runs with multiple backend workers
  • [ ] Token / cost metering per clinic — billing dashboard

Non-goals (deferred indefinitely)

  • LLM provider abstraction in core — each agent imports its own SDK
  • Multi-agent coordination — agents communicate via the existing event bus, not a custom protocol
  • Vector DB / RAG primitives — add only when a concrete agent requires them

9. COMPLIANCE & SECURITY

GDPR 🟠 P1

FeatureDescription
Consent managementConsent tracking by channel
Right of accessPatient data export
Right to erasureAnonymization/deletion workflow
Data minimizationConfigurable retention periods
Breach notificationNotification workflow

Audit Log 🔴 P0

FeatureDescription
ImmutableAppend-only, no tampering
CompleteWho, what, when, where, before/after
SearchableFilterable by user, entity, date
ExportableFor external audits
RetentionConfigurable policies

Backup & DR 🟠 P1

FeatureDescription
Automated dailyDatabase + files
Point-in-timeWAL-based recovery
Cross-regionOptional replication
One-click restoreEasy recovery
EncryptionAt rest

10. MODULE ARCHITECTURE

Module Anatomy

python
# backend/app/modules/mymodule/__init__.py
class MyModule(BaseModule):
    @property
    def name(self) -> str:
        return "mymodule"  # Router at /api/v1/mymodule/

    @property
    def version(self) -> str:
        return "0.1.0"

    @property
    def dependencies(self) -> list[str]:
        return ["clinical"]  # Loaded after clinical

    def get_models(self) -> list:
        return [MyModel]

    def get_router(self) -> APIRouter:
        return router

    def get_permissions(self) -> list[str]:
        return ["resource.read", "resource.write"]

    def get_event_handlers(self) -> dict:
        return {"patient.created": self._on_patient_created}

    def get_ai_tools(self) -> list:  # AI-native
        return [CreateResourceTool(), ListResourcesTool()]

Event Bus

python
# Publishing
from app.core.events import event_bus
event_bus.publish("patient.created", {"patient_id": str(patient.id)})

# Subscribing
def get_event_handlers(self) -> dict:
    return {"patient.created": self._handle}

Frontend Extension Points

Extension PointUse
NavigationRegister menu items
Patient tabsAdd tabs to patient record
Dashboard widgetsCards on main dashboard
Action buttonsContextual buttons
Settings pagesConfiguration pages

11. EXECUTIVE SUMMARY

What is DentalPin

Open source dental clinic management software:

  • Free core generates adoption and ecosystem
  • Modular architecture enables third-party integrations
  • BSL 1.1 license protects against SaaS competitors while allowing free use

Why it exists

  1. The dental software market is fragmented and legacy
  2. Clinics deserve modern, open, affordable software
  3. An open standard benefits the entire industry

What to build first

  1. 🔴 Complete patient record — Without this, no MVP
  2. Catalog — Treatment catalog implemented
  3. 🔴 Budgets + Billing — The revenue workflow (depends on catalog ✅)
  4. 🟠 Verifactu — Mandatory legal compliance
  5. 🟠 Inventory — Stock and supplies management

How we measure success

Primary metric: Active clinics using DentalPin daily.

Everything else (stars, contributors, modules) are supporting indicators.