# benzarti-ahmed-yassine/medierp architecture

> Architecture diagram of the GitHub repository benzarti-ahmed-yassine/medierp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/benzarti-ahmed-yassine/medierp
- Repository: https://github.com/benzarti-ahmed-yassine/medierp

## Overview

1. **System shape**
   - MediERP Professional is a **desktop ERP for medical practice** built in **Python** with **PySide6/PyQt-style UI**.
   - The runtime is centered around `main.py`, which boots the app and connects the UI layer to the core/application services.

2. **Primary layering**
   - The repository is organized into four main layers: `src/core` for application infrastructure, `src/views` for screens/widgets, `src/services` for business/AI/automation services, and `src/models` for domain entities.
   - `src/utils` contains cross-cutting helpers, including Qt compatibility support.

3. **Core platform layer**
   - `src/core` holds the non-UI backbone: application lifecycle (`app.py`), database access (`database.py`), event coordination (`events.py`), RBAC enforcement (`rbac.py`), security primitives (`security.py`), and theming (`theme_manager.py`, `theme_definitions.py`).
   - This layer is the main boundary between the desktop UI and persistence/security concerns.

4. **Role-based UI architecture**
   - `src/views` is split by role: **admin**, **doctor**, **assistant**, **secretary**, and **patient**.
   - Each role has dedicated dashboards and task views, which reflects the product’s RBAC model and keeps the user flows separated by persona.

5. **End-to-end clinical workflow**
   - The README describes a connected workflow: **arrival → vitals capture by assistant → doctor consultation with AI support → billing by secretary**.
   - The views mirror this: assistant screens for patients, inventory, and vital signs; doctor screens for agenda, messages, prescriptions, and patient selection; secretary screens for agenda, billing, and finance.

6. **Data model and persistence**
   - `src/models` provides shared domain objects such as `Patient` and `User`, with `base.py` as the common model foundation.
   - Persistence is backed by **SQLite** using the `database/` folder for schema and migrations, and `db/` for local database/document artifacts.

7. **Schema evolution and migration strategy**
   - The `database/migrations` directory contains multiple SQL migrations, including RBAC, security, messaging, notifications, system config, and feature updates.
   - This indicates the database schema is versioned and evolved through scripted SQL rather than an ORM-heavy migration framework.

8. **Service layer responsibilities**
   - `src/services` contains the operational logic that sits behind the UI: `ml_service.py` for predictive risk scoring, `biometric_service.py` and `face_service.py` for biometric auth, `pdf_service.py` for document generation, and `email_service.py` / `reminder_service.py` / `report_service.py` for communication and automation.
   - These services are the main integration boundary for non-UI capabilities.

9. **AI and biometrics as first-class subsystems**
   - The ML assets in `assets/models/` include a trained heart-risk model and scaler, showing the predictive component is embedded locally rather than called from an external API.
   - Biometric authentication is also local and integrated into the desktop app, reinforcing the app’s offline-capable, privacy-sensitive architecture.

10. **Document and reporting outputs**
   - Generated artifacts appear under `docs/exports/` and `db/documents/`, including PDF prescriptions/ordonnances.
   - This suggests the application produces clinical documents locally and stores them alongside the database files rather than in a remote document service.

11. **Configuration and presentation layer**
   - `config/settings.json`, `.env.example`, and QSS/theme files define runtime configuration and visual styling.
   - The repo uses a “Full Light” desktop theme, so UI presentation is controlled centrally rather than per-view.

12. **Administration and governance**
   - The admin area covers user management, audit, and system settings, which aligns with the RBAC-heavy design.
   - `src/core/rbac.py` and the admin views form the governance boundary for permissions, account lifecycle, and operational oversight.

13. **Testing and operational scripts**
   - `tests/` includes coverage for basic behavior, biometrics, and ML, which reflects the project’s risk areas.
   - `src/scripts/`, `scratch/`, and standalone helpers like `launch_test.py` are operational utilities for database initialization, password resets, migrations, and environment checks; they are support tooling, not core runtime subsystems.

14. **How to diagram it**
   - A clean architecture diagram should place the **desktop UI/views** at the top, fed by **core app/security/RBAC/database** in the middle, with **services** branching to ML, biometrics, PDF, email, and reminders, and **SQLite + local assets/documents** at the bottom as persistence/artifact stores.
   - The key business boundary is role-based access: each persona view talks to the same core and service layers but exposes different workflows and datasets.

Main entry points: [`src/views/main_window.py`](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/main_window.py) (Main window), [`src/core/app.py`](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/core/app.py) (App core), [`src/core/database.py`](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/core/database.py) (Database), [`src/views/admin/admin_dashboard_view.py`](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/admin/admin_dashboard_view.py) (Admin dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry"]
  node_main["Main app<br/>bootstrap<br/>[main.py]"]
end

subgraph group_core["Core Platform"]
  node_app_core["App core<br/>lifecycle<br/>[app.py]"]
  node_db_core[("Database<br/>persistence<br/>[database.py]")]
  node_events_core(("Events<br/>coordination<br/>[events.py]"))
  node_rbac_core{{"RBAC<br/>authorization<br/>[rbac.py]"}}
  node_security_core{{"Security<br/>auth<br/>[security.py]"}}
  node_theme_core["Theme<br/>presentation<br/>[theme_manager.py]"]
end

subgraph group_views["Views"]
  node_main_window["Main window<br/>shell<br/>[main_window.py]"]
  node_login_view["Login<br/>auth view<br/>[login_view.py]"]
  node_admin_dash["Admin dashboard<br/>admin view"]
  node_doctor_dash["Doctor dashboard<br/>doctor view"]
  node_assistant_dash["Assistant dashboard<br/>assistant view"]
  node_secretary_dash["Secretary dashboard<br/>secretary view"]
  node_patient_portal["Patient portal<br/>patient view"]
  node_consultation["Consultation<br/>clinical workflow"]
  node_biometric_widget["Biometric auth<br/>ui widget"]
end

subgraph group_services["Services"]
  node_ml_service["ML service<br/>predictive scoring<br/>[ml_service.py]"]
  node_bio_service["Biometrics<br/>identity service"]
  node_pdf_service["PDF output<br/>document service<br/>[pdf_service.py]"]
  node_email_service["Messaging<br/>communication service<br/>[email_service.py]"]
  node_reminder_service["Reminders<br/>automation service"]
  node_report_service["Reports<br/>reporting service<br/>[report_service.py]"]
end

subgraph group_data["Data & Assets"]
  node_patient_model["Patient<br/>domain model<br/>[patient.py]"]
  node_user_model["User<br/>domain model<br/>[user.py]"]
  node_schema[("Schema<br/>[schema.sql]")]
  node_migrations["Migrations"]
  node_exports["Exports<br/>generated documents"]
  node_documents["Local docs<br/>document store"]
  node_models_assets[("ML assets<br/>model artifacts")]
end

node_main -->|"boots"| node_app_core
node_main -->|"opens"| node_main_window
node_app_core -->|"uses"| node_db_core
node_app_core -->|"publishes"| node_events_core
node_app_core -->|"enforces"| node_rbac_core
node_app_core -->|"secures"| node_security_core
node_app_core -->|"configures"| node_theme_core
node_main_window -->|"hosts"| node_login_view
node_main_window -->|"routes"| node_admin_dash
node_main_window -->|"routes"| node_doctor_dash
node_main_window -->|"routes"| node_assistant_dash
node_main_window -->|"routes"| node_secretary_dash
node_main_window -->|"routes"| node_patient_portal
node_login_view -->|"authenticates"| node_biometric_widget
node_biometric_widget -->|"calls"| node_bio_service
node_doctor_dash -->|"opens"| node_consultation
node_consultation -->|"scores"| node_ml_service
node_consultation -->|"prints"| node_pdf_service
node_assistant_dash -->|"verifies"| node_bio_service
node_secretary_dash -->|"sends"| node_email_service
node_secretary_dash -->|"schedules"| node_reminder_service
node_admin_dash -->|"reviews"| node_report_service
node_admin_dash -->|"governs"| node_rbac_core
node_patient_portal -->|"listens"| node_events_core
node_patient_model -->|"persists"| node_db_core
node_user_model -->|"binds"| node_rbac_core
node_db_core -->|"loads"| node_schema
node_db_core -->|"evolves"| node_migrations
node_pdf_service -->|"writes"| node_exports
node_pdf_service -->|"archives"| node_documents
node_ml_service -->|"loads"| node_models_assets

click node_main "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/main.py"
click node_app_core "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/core/app.py"
click node_db_core "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/core/database.py"
click node_events_core "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/core/events.py"
click node_rbac_core "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/core/rbac.py"
click node_security_core "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/core/security.py"
click node_theme_core "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/core/theme_manager.py"
click node_main_window "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/main_window.py"
click node_login_view "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/login_view.py"
click node_admin_dash "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/admin/admin_dashboard_view.py"
click node_doctor_dash "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/doctor/doctor_dashboard_view.py"
click node_assistant_dash "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/assistant/assistant_dashboard_view.py"
click node_secretary_dash "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/secretary/secretary_dashboard_view.py"
click node_patient_portal "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/patient/patient_portal_view.py"
click node_consultation "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/consultation_view.py"
click node_biometric_widget "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/biometric_widget.py"
click node_ml_service "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/services/ml_service.py"
click node_bio_service "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/services/biometric_service.py"
click node_pdf_service "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/services/pdf_service.py"
click node_email_service "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/services/email_service.py"
click node_reminder_service "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/services/reminder_service.py"
click node_report_service "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/services/report_service.py"
click node_patient_model "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/models/patient.py"
click node_user_model "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/models/user.py"
click node_schema "https://github.com/benzarti-ahmed-yassine/medierp/blob/main/database/schema.sql"
click node_migrations "https://github.com/benzarti-ahmed-yassine/medierp/tree/main/database/migrations"
click node_exports "https://github.com/benzarti-ahmed-yassine/medierp/tree/main/docs/exports"
click node_documents "https://github.com/benzarti-ahmed-yassine/medierp/tree/main/db/documents"
click node_models_assets "https://github.com/benzarti-ahmed-yassine/medierp/tree/main/assets/models"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main toneBlue
class node_app_core,node_db_core,node_events_core,node_rbac_core,node_security_core,node_theme_core toneAmber
class node_main_window,node_login_view,node_admin_dash,node_doctor_dash,node_assistant_dash,node_secretary_dash,node_patient_portal,node_consultation,node_biometric_widget toneMint
class node_ml_service,node_bio_service,node_pdf_service,node_email_service,node_reminder_service,node_report_service toneRose
class node_patient_model,node_user_model,node_schema,node_migrations,node_exports,node_documents,node_models_assets toneIndigo
```

## Components

### Entry

Application bootstrap and top-level shell

- [Main app](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/main.py): bootstrap · Starts the desktop application and wires core and UI · `main.py`

### Core Platform

Application lifecycle, security, events, and database boundaries

- [App core](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/core/app.py): lifecycle · Application startup, shutdown, and runtime wiring · `src/core/app.py`
- [Database](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/core/database.py): persistence · SQLite access and data coordination · `src/core/database.py`
- [Events](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/core/events.py): coordination · App-wide event signaling and dispatch · `src/core/events.py`
- [RBAC](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/core/rbac.py): authorization · Role and permission enforcement · `src/core/rbac.py`
- [Security](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/core/security.py): auth · Security primitives and protected operations · `src/core/security.py`
- [Theme](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/core/theme_manager.py): presentation · Central theme definitions and theme switching · `src/core/theme_manager.py`

### Views

Role-based desktop screens and shared UI

- [Main window](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/main_window.py): shell · Primary desktop shell hosting role-specific screens · `src/views/main_window.py`
- [Login](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/login_view.py): auth view · Entry screen for desktop authentication · `src/views/login_view.py`
- [Admin dashboard](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/admin/admin_dashboard_view.py): admin view · Governance and system oversight home screen · `src/views/admin/admin_dashboard_view.py`
- [Doctor dashboard](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/doctor/doctor_dashboard_view.py): doctor view · Clinical workflow entry for physicians · `src/views/doctor/doctor_dashboard_view.py`
- [Assistant dashboard](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/assistant/assistant_dashboard_view.py): assistant view · Front-desk and vitals workflow entry · `src/views/assistant/assistant_dashboard_view.py`
- [Secretary dashboard](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/secretary/secretary_dashboard_view.py): secretary view · Billing and agenda workflow entry · `src/views/secretary/secretary_dashboard_view.py`
- [Patient portal](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/patient/patient_portal_view.py): patient view · Patient-facing portal and self-service views · `src/views/patient/patient_portal_view.py`
- [Consultation](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/consultation_view.py): clinical workflow · Doctor consultation workspace with shared patient context · `src/views/consultation_view.py`
- [Biometric auth](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/views/biometric_widget.py): ui widget · Local biometric login and identity capture widget · `src/views/biometric_widget.py`

### Services

Operational services behind the UI

- [ML service](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/services/ml_service.py): predictive scoring · Risk scoring and local model inference · `src/services/ml_service.py`
- [Biometrics](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/services/biometric_service.py): identity service · Biometric and face-based authentication support · `src/services/biometric_service.py`
- [PDF output](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/services/pdf_service.py): document service · Generates prescriptions and other clinical PDFs · `src/services/pdf_service.py`
- [Messaging](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/services/email_service.py): communication service · Email-based communication and delivery · `src/services/email_service.py`
- [Reminders](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/services/reminder_service.py): automation service · Scheduled reminders and notification automation · `src/services/reminder_service.py`
- [Reports](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/services/report_service.py): reporting service · Aggregates operational and business reports · `src/services/report_service.py`

### Data & Assets

Persistent store, schema, exports, and ML artifacts

- [Patient](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/models/patient.py): domain model · Core patient entity shared across workflows · `src/models/patient.py`
- [User](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/src/models/user.py): domain model · Application user and role-bearing identity · `src/models/user.py`
- [Schema](https://github.com/benzarti-ahmed-yassine/medierp/blob/main/database/schema.sql): sql schema · Base schema and migration scripts for the database · `database/schema.sql`
- [Migrations](https://github.com/benzarti-ahmed-yassine/medierp/tree/main/database/migrations): sql migrations · Versioned schema evolution scripts · `database/migrations`
- [Exports](https://github.com/benzarti-ahmed-yassine/medierp/tree/main/docs/exports): generated documents · Generated PDFs and exported clinical documents · `docs/exports`
- [Local docs](https://github.com/benzarti-ahmed-yassine/medierp/tree/main/db/documents): document store · Database-backed local document artifacts · `db/documents`
- [ML assets](https://github.com/benzarti-ahmed-yassine/medierp/tree/main/assets/models): model artifacts · Local trained model and scaler artifacts · `assets/models`

## Connections

- Main app → App core: boots · Main entry initializes the application runtime
- Main app → Main window: opens · Application bootstraps the desktop shell
- App core → Database: uses · Core app wires persistence services
- App core → Events: publishes · Application lifecycle emits shared events
- App core → RBAC: enforces · Role checks gate application actions
- App core → Security: secures · Security primitives protect the runtime
- App core → Theme: configures · Core app sets and updates global theme
- Main window → Login: hosts · Shell starts with authentication flow
- Main window → Admin dashboard: routes · Admin persona is routed into governance screens
- Main window → Doctor dashboard: routes · Doctor persona is routed into clinical screens
- Main window → Assistant dashboard: routes · Assistant persona is routed into intake screens
- Main window → Secretary dashboard: routes · Secretary persona is routed into billing screens
- Main window → Patient portal: routes · Patient persona is routed into self-service screens
- Login → Biometric auth: authenticates · Login can use biometric identity capture
- Biometric auth → Biometrics: calls · Widget delegates biometric verification to services
- Doctor dashboard → Consultation: opens · Doctor dashboard leads into consultation workflow
- Consultation → ML service: scores · Consultation can request local risk prediction
- Consultation → PDF output: prints · Clinical workflow can generate prescriptions and PDFs
- Assistant dashboard → Biometrics: verifies · Assistant intake can authenticate by biometrics
- Secretary dashboard → Messaging: sends · Billing and agenda flows can notify by email
- Secretary dashboard → Reminders: schedules · Secretary workflow triggers reminders
- Admin dashboard → Reports: reviews · Admin oversight uses reports and operational summaries
- Admin dashboard → RBAC: governs · Admin screens manage roles and permissions
- Patient portal → Events: listens · Patient-facing screens react to shared app events
- Patient → Database: persists · Domain data is stored through the database layer
- User → RBAC: binds · Users carry role information used by RBAC
- Database → Schema: loads · Database layer is defined by schema files
- Database → Migrations: evolves · Database changes are applied through migrations
- PDF output → Exports: writes · Generated PDFs are exported to docs storage
- PDF output → Local docs: archives · Clinical documents are kept in local document storage
- ML service → ML assets: loads · Risk scoring uses local serialized model assets