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 System✅Auto-discovery, dependency resolution
Auth + RBAC✅JWT, 5 roles, wildcard permissions
Event Bus✅Pub/sub for module communication
Multi-tenancy✅Clinic isolation, membership
REST API✅OpenAPI, versioned

3.2 First-Party Modules (BSL 1.1) ​

Included by default. Functionality every clinic needs.

ModuleStatusFunction
clinical⚠️ PartialPatients, appointments (basic)
odontogram✅Interactive FDI dental chart
catalog✅Treatment 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 module✅BaseModule subclass with dependencies: ["clinical"]
StorageBackend protocol✅upload, download, delete, get_url methods
LocalStorage implementation✅Docker volume mount, path-based storage
Document model✅patient_id, document_type, filename, storage_path, mime_type, file_size, title, description, metadata (JSONB), uploaded_by
Upload endpoint✅POST /patients/{id}/documents with multipart form, validation (size, type)
List/Get/Delete endpoints✅Standard CRUD with permission checks
Download endpoint✅Streaming response with correct content-type
Permissions✅media.documents.read/write
File validation✅Max size (10MB default), allowed MIME types
Alembic migration✅o5p6q7r8s9t0_add_documents_table.py

Frontend Tasks:

TaskStatusDescription
useDocuments composable✅fetchDocuments, uploadDocument, downloadDocument, deleteDocument, updateDocument
DocumentUpload component✅Drag-drop zone, progress indicator, type selector
DocumentGallery component✅Grid view, type filter, pagination
DocumentCard component✅PDF/image icon, title, type badge, download/edit/delete actions
DocumentViewer component🔴PDF inline viewer, image lightbox (not implemented)
Add Documents tab to patient✅Separate Documents tab in patient detail
i18n translations✅Spanish 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 codes✅Per-clinic internal treatment codes
Multi-language✅Localized names and descriptions (i18n)
Categories✅Hierarchical categories with icons
Pricing✅Default price + cost price tracking
Duration✅Default times for scheduling integration
VAT✅Configurable VAT types per clinic
Odontogram mapping✅Link treatments to odontogram visualization
Treatment scope✅Surface 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
catalog✅Treatment catalog with VAT types, odontogram mapping
budgets✅Budgets with complete workflow + PDF
billing✅Basic 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
ToolRegistry✅Namespaced registry, JSON Schema helper, single-chokepoint call()
BaseAgent + AgentContext✅Abstract 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
Guardrails✅Rate limits, blocked tools, require-approval patterns, auto-approval for DESTRUCTIVE / supervised-WRITE
Audit log✅agent_audit_logs table, every tool attempt recorded
Approval queue (backend)✅agent_approval_queue + service + endpoints
agents.* RBAC✅agents.view/supervise/configure/manage permissions
Docs✅docs/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.