# the-software-squad/hms-app architecture

> Architecture diagram of the GitHub repository the-software-squad/hms-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/the-software-squad/hms-app
- Repository: https://github.com/the-software-squad/hms-app

## Overview

##### Project type and purpose
- This is a Frappe-based Hospital Management System (HMS) app that plugs into a Frappe/ERPNext bench.
- It provides domain models (Doctypes) for patients, visits, billing, lab reports, inventory, dashboards, print formats, and APIs.

##### File structure
- Top-level: configuration files (.eslintrc, pyproject.toml, hooks.py), fixtures, API endpoints, tasks, public assets, templates.
- hms/hms/doctype/: each folder is a Frappe DocType (model + schema JSON + server-side Python + client JS + tests).
- hms/hms/dashboard_chart/, number_card/, workspace/ and print_format/: metadata JSON driving UI widgets and dashboards.
- hms/api/: custom REST routes (patient.py).
- fixtures/: seed data (roles, HTML blocks).

##### README
- Confirms this is a Frappe “app” installed via bench.
- No external infra—relies on Frappe’s server, database, web client.

##### Main components
a. Frappe Framework
- Python-based server, DocType engine, hooks system (hooks.py), background tasks (tasks.py), fixtures loader.
b. HMS App
- Doctype modules (business objects + logic)
- Dashboard / number card metadata
- Print format definitions
- API layer (hms/api/*.py)
- Frontend extensions (doctype/*.js + templates/pages)
c. Database
- MariaDB (stores DocType tables and app data)
d. Web Client
- Frappe desk UI, pages, forms, charts, dashboards
e. Bench CLI / Deployment
- bench get-app, bench install-app, pre-commit hooks

##### Relationships and interactions
- Web Client ↔ HTTP(S) ↔ Frappe Server
- Frappe Server loads HMS app modules via hooks.py, serves DocType form APIs, chart JSON endpoints, custom REST endpoints.
- Frappe Server ↔ ORM ↔ MariaDB
- fixtures → initial seed on “bench migrate”
- tasks.py → Celery/Worker (if configured) for background jobs

##### Architectural patterns and design principles
- MVC/MVVM: DocTypes = Model + Controller (Python) + View metadata (JSON + JS)
- Convention-over-configuration: folder structure maps to DocType names
- Extensibility via hooks and custom API
- Metadata-driven UI (dashboard_chart, number_card JSON)

##### Technologies and frameworks
- Python 3 + Frappe framework
- JavaScript (ESLint + Prettier) for client scripts
- MariaDB (or MySQL)
- Bench CLI
- pre-commit tooling: ruff, eslint, prettier, pyupgrade

##### Detail but keep focus
- HMS sub-modules (doctype, chart, card, print format, API)
- Do not clutter with every single Doctype–group them logically (e.g. “Clinical Doctypes”, “Administrative Doctypes”)
- Data flows: UI → API → Model → DB → UI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Browser UI: Desk, Forms, Charts, Print"]:::ui
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB

        subgraph "Frappe Core"
            direction TB
            FrappeServer["Frappe Server"]:::backend
            Hooks["hooks.py"]:::backend
            Tasks["tasks.py"]:::backend
        end

        subgraph "HMS App"
            direction TB

            subgraph "Doctype Modules"
                direction TB
                Patient["Patient Doctype"]:::backend
                PatientVisit["Patient Visit Doctype"]:::backend
                LabReport["Lab Report Doctype"]:::backend
            end

            subgraph "API Layer"
                direction TB
                PatientAPI["Patient Endpoints"]:::backend
            end

            subgraph "Metadata"
                direction TB
                DashboardCharts["Dashboard Charts JSON"]:::ui
                NumberCards["Number Cards JSON"]:::ui
                PrintFormats["Print Formats JSON"]:::ui
                Workspaces["Workspace Configs JSON"]:::ui
            end

            subgraph "Fixtures Loader"
                direction TB
                FixturesLoader["Fixtures Loader"]:::backend
            end

            subgraph "Public & Templates"
                direction TB
                Public["Public Static Assets"]:::ui
                Templates["Page Templates"]:::ui
            end

        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        MariaDB["MariaDB"]:::db
    end

    %% Tooling
    subgraph "Tooling"
        direction TB
        BenchCLI["Bench CLI"]:::tooling
        PreCommit["Pre-commit Hooks"]:::tooling
    end

    %% Connections
    Browser -->|"HTTP(S) Requests"| FrappeServer
    FrappeServer -->|"CRUD via ORM"| MariaDB
    MariaDB -->|"Data"| FrappeServer
    FrappeServer -->|"Render HTML/JSON"| Browser

    Browser -->|"GET /api/patient"| PatientAPI
    PatientAPI -->|"Dispatch"| FrappeServer
    FrappeServer -->|"Load Modules via Hooks"| Hooks
    FrappeServer -->|"Schedule Tasks"| Tasks
    FrappeServer -->|"Load Fixtures on migrate"| FixturesLoader

    FrappeServer -->|"Serve Doctype Models"| Patient
    FrappeServer -->|"Serve Doctype Models"| PatientVisit
    FrappeServer -->|"Serve Doctype Models"| LabReport

    FrappeServer -->|"Serve Metadata"| DashboardCharts
    FrappeServer -->|"Serve Metadata"| NumberCards
    FrappeServer -->|"Serve Metadata"| PrintFormats
    FrappeServer -->|"Serve Metadata"| Workspaces

    BenchCLI -->|"install-app / get-app"| FrappeServer
    PreCommit -->|"Lint/Format"| Hooks

    %% Click Events
    click Hooks "https://github.com/the-software-squad/hms-app/blob/develop/hms/hooks.py"
    click Tasks "https://github.com/the-software-squad/hms-app/blob/develop/hms/tasks.py"
    click PatientAPI "https://github.com/the-software-squad/hms-app/blob/develop/hms/api/patient.py"
    click FixturesLoader "https://github.com/the-software-squad/hms-app/blob/develop/hms/fixtures/custom_html_block.json"
    click FixturesLoader "https://github.com/the-software-squad/hms-app/blob/develop/hms/fixtures/role.json"
    click Patient "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/doctype/patient/patient.py"
    click Patient "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/doctype/patient/patient.json"
    click Patient "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/doctype/patient/patient.js"
    click Patient "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/doctype/patient/test_patient.py"
    click PatientVisit "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/doctype/patient_visit/patient_visit.py"
    click PatientVisit "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/doctype/patient_visit/patient_visit.json"
    click PatientVisit "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/doctype/patient_visit/patient_visit.js"
    click PatientVisit "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/doctype/patient_visit/test_patient_visit.py"
    click LabReport "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/doctype/lab_report/lab_report.py"
    click LabReport "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/doctype/lab_report/lab_report.json"
    click LabReport "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/doctype/lab_report/lab_report.js"
    click LabReport "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/doctype/lab_report/test_lab_report.py"
    click DashboardCharts "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/dashboard_chart/by_purpose/by_purpose.json"
    click DashboardCharts "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/dashboard_chart/payment_mode/payment_mode.json"
    click DashboardCharts "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/dashboard_chart/total_collection/total_collection.json"
    click NumberCards "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/number_card/new_patients_today/new_patients_today.json"
    click NumberCards "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/number_card/total_collection/total_collection.json"
    click NumberCards "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/number_card/total_patient_vists/total_patient_vists.json"
    click PrintFormats "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/print_format/op_recipt/op_recipt.json"
    click Workspaces "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/workspace/accounts/accounts.json"
    click Workspaces "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/workspace/analytics/analytics.json"
    click Workspaces "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/workspace/doctor_dashboard/doctor_dashboard.json"
    click Workspaces "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/workspace/pharmacist_dashboard/pharmacist_dashboard.json"
    click Workspaces "https://github.com/the-software-squad/hms-app/blob/develop/hms/hms/workspace/reception_dashboard/reception_dashboard.json"
    click Public "https://github.com/the-software-squad/hms-app/tree/develop/hms/public"
    click Templates "https://github.com/the-software-squad/hms-app/tree/develop/hms/templates/pages"
    click BenchCLI "https://github.com/the-software-squad/hms-app/blob/develop/pyproject.toml"
    click BenchCLI "https://github.com/the-software-squad/hms-app/blob/develop/.eslintrc"
    click BenchCLI "https://github.com/the-software-squad/hms-app/blob/develop/.pre-commit-config.yaml"
    click BenchCLI "https://github.com/the-software-squad/hms-app/blob/develop/hms/modules.txt"
    click BenchCLI "https://github.com/the-software-squad/hms-app/blob/develop/hms/patches.txt"

    %% Styles
    classDef backend fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef ui fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32
    classDef db fill:#ffe0b2,stroke:#e65100,color:#e65100
    classDef tooling fill:#e0e0e0,stroke:#424242,color:#424242
```
