# juls-33/rbtc-ims architecture

> Architecture diagram of the GitHub repository juls-33/rbtc-ims, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/juls-33/rbtc-ims
- Repository: https://github.com/juls-33/rbtc-ims

## Overview

1. **Overall shape**
   - This is a Laravel 12 “modern monolith”: the backend serves both application logic and the SPA shell, while React 19 handles the interactive UI through Inertia.js.
   - There is no separate public API layer; the main boundary is between Laravel controllers/models and the React pages under `resources/js`.

2. **Request entry and composition**
   - HTTP traffic enters through `public/index.php`, is routed by `routes/web.php` and `routes/auth.php`, and is handled by Laravel controllers in `app/Http/Controllers`.
   - Inertia middleware (`app/Http/Middleware/HandleInertiaRequests.php`) bridges server-side routing with React page rendering.

3. **Core domain areas**
   - The system centers on patient care and operations: patients, admissions, visits, prescriptions, rooms/room stays, medicine inventory, billing, archives, and staff administration.
   - The main domain models live in `app/Models`, with migrations defining the database schema and foreign-key relationships.

4. **Role-based application slices**
   - The frontend is organized by user role: `resources/js/Pages/Admin`, `Doctor`, `Nurse`, plus shared auth and profile pages.
   - Backend access is similarly constrained through middleware such as `DoctorMiddleware`, `NurseMiddleware`, `CheckAccountStatus`, and `ForcePasswordChange`, so diagrammatically this is a role-gated system rather than a single flat app.

5. **Authentication and staff identity**
   - Authentication is built around the `staff` table and the auth controllers under `app/Http/Controllers/Auth`.
   - The auth flow supports registration, login, email verification, password reset/confirmation, and a forced password-change path, indicating staff accounts are first-class security principals.

6. **Patient workflow**
   - Patient management spans creation, editing, visiting, admission/discharge, and logging.
   - Related backend components include `PatientController`, `AdmissionController`, `PatientVisitController`, `PatientLogController`, and archive support, while the React side contains modal-driven screens for adding/editing/deleting and viewing patient profiles and logs.

7. **Hospital/clinical operations**
   - Clinical work is split between doctors and nurses, each with dedicated dashboards and patient-facing screens.
   - The data flow appears to be: staff opens a role-specific dashboard, views patients, records visits/vitals, creates prescriptions, and stores operational history in visit/log tables.

8. **Inventory and medication control**
   - Medicine inventory is modeled explicitly with catalogs, batches, stock logs, medication logs, and prescription records.
   - This suggests a stock-tracked flow: medicine catalog -> batch inventory -> prescription/dispense action -> stock/medication logs, with admin UI components for managing batches and stock ledgers.

9. **Billing and invoices**
   - Billing is split into outpatient and inpatient paths, with separate controllers and bill item models for each.
   - Printable invoice rendering is handled by Blade views in `resources/views/inpatient_invoice.blade.php` and `outpatient_invoice.blade.php`, so billing combines SPA management screens with server-rendered document output.

10. **Persistence model and schema evolution**
   - The database is MySQL, and the migration history shows continuous evolution of key tables: soft deletes, billing redesigns, added vitals, room stays, monthly rates, and security fields.
   - Factories and seeders support realistic test/dev data for patients, rooms, staff, medicine, and inpatient scenarios.

11. **Security and searchable data**
   - The project explicitly uses CipherSweet and Sodium for encrypted/searchable data, which materially affects schema design and runtime requirements.
   - The README’s PHP extension requirements matter because encryption/search features depend on those extensions being available.

12. **Frontend structure**
   - React pages live under `resources/js/Pages`, shared UI widgets under `resources/js/Components`, and common layouts under `resources/js/Layouts`.
   - The UI is heavily componentized around modals, tables, stats cards, notifications, and form controls, which matches a CRUD-heavy internal system.

13. **Operational tooling**
   - Vite builds the frontend, Tailwind provides styling, and PHPUnit covers backend/auth/profile features.
   - GitHub Actions run tests and maintenance workflows, including changelog updates, which indicates the repo is treated as a maintained production application.

14. **Key diagram boundaries**
   - A useful architecture diagram should show: browser/UI → Inertia/Laravel controllers → domain models → MySQL, with a side path for auth/middleware and a separate path for printable invoice generation.
   - On the client side, divide the SPA into admin, doctor, nurse, auth, and shared component areas; on the server side, divide into controllers, middleware, models, migrations, and security/encryption support.

Main entry points: [`app/Http/Controllers/DashboardController.php`](https://github.com/juls-33/rbtc-ims/blob/main/app/Http/Controllers/DashboardController.php) (Controllers), [`database/migrations/2026_01_09_122923_create_patients_table.php`](https://github.com/juls-33/rbtc-ims/blob/main/database/migrations/2026_01_09_122923_create_patients_table.php) (Migrations), [`resources/js/app.jsx`](https://github.com/juls-33/rbtc-ims/blob/main/resources/js/app.jsx) (SPA shell), [`public/index.php`](https://github.com/juls-33/rbtc-ims/blob/main/public/index.php) (Entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_browser(("Browser<br/>ui client"))
  node_spa_shell["SPA shell<br/>react entry<br/>[app.jsx]"]
  node_role_pages["Role pages<br/>react pages"]
  node_shared_ui["Shared UI<br/>react components<br/>[Modal.jsx]"]
end

subgraph group_http["HTTP App"]
  node_public_index["Entry<br/>php front controller<br/>[index.php]"]
  node_web_routes["Web routes<br/>route map<br/>[web.php]"]
  node_auth_routes["Auth routes<br/>route map<br/>[auth.php]"]
  node_controllers["Controllers"]
  node_auth_controllers["Auth flow<br/>auth controllers"]
  node_inertia["Inertia bridge<br/>middleware"]
  node_guards["Access guards<br/>middleware"]
end

subgraph group_domain["Domain"]
  node_patient_ops["Patient ops<br/>domain workflow<br/>[Patient.php]"]
  node_inventory["Inventory<br/>domain workflow"]
  node_billing["Billing<br/>domain workflow"]
  node_staff["Staff identity<br/>security domain<br/>[Staff.php]"]
end

subgraph group_data["Data"]
  node_migrations["Migrations<br/>schema evolution"]
  node_db[("MySQL<br/>database<br/>[database.php]")]
  node_ciphersweet["CipherSweet<br/>encryption config<br/>[ciphersweet.php]"]
end

subgraph group_output["Output"]
  node_invoices["Invoices<br/>blade views"]
end

node_browser -->|"requests"| node_public_index
node_public_index -->|"dispatches"| node_web_routes
node_public_index -->|"auth dispatch"| node_auth_routes
node_web_routes -->|"handles"| node_controllers
node_auth_routes -->|"handles"| node_auth_controllers
node_controllers -->|"protected by"| node_guards
node_auth_controllers -->|"checks"| node_guards
node_controllers -->|"renders"| node_inertia
node_inertia -->|"bootstraps"| node_spa_shell
node_spa_shell -->|"loads"| node_role_pages
node_spa_shell -->|"composes"| node_shared_ui
node_role_pages -->|"actions"| node_controllers
node_controllers -->|"orchestrates"| node_patient_ops
node_controllers -->|"orchestrates"| node_inventory
node_controllers -->|"orchestrates"| node_billing
node_controllers -->|"manages"| node_staff
node_patient_ops -->|"persisted by"| node_migrations
node_inventory -->|"persisted by"| node_migrations
node_billing -->|"persisted by"| node_migrations
node_staff -->|"persisted by"| node_migrations
node_migrations -->|"applies to"| node_db
node_staff -->|"secured by"| node_ciphersweet
node_billing -->|"prints"| node_invoices

click node_public_index "https://github.com/juls-33/rbtc-ims/blob/main/public/index.php"
click node_web_routes "https://github.com/juls-33/rbtc-ims/blob/main/routes/web.php"
click node_auth_routes "https://github.com/juls-33/rbtc-ims/blob/main/routes/auth.php"
click node_controllers "https://github.com/juls-33/rbtc-ims/blob/main/app/Http/Controllers/DashboardController.php"
click node_auth_controllers "https://github.com/juls-33/rbtc-ims/blob/main/app/Http/Controllers/Auth/AuthenticatedSessionController.php"
click node_inertia "https://github.com/juls-33/rbtc-ims/blob/main/app/Http/Middleware/HandleInertiaRequests.php"
click node_guards "https://github.com/juls-33/rbtc-ims/blob/main/app/Http/Middleware/DoctorMiddleware.php"
click node_spa_shell "https://github.com/juls-33/rbtc-ims/blob/main/resources/js/app.jsx"
click node_role_pages "https://github.com/juls-33/rbtc-ims/blob/main/resources/js/Pages/Admin/PatientManagement.jsx"
click node_shared_ui "https://github.com/juls-33/rbtc-ims/blob/main/resources/js/Components/Modal.jsx"
click node_patient_ops "https://github.com/juls-33/rbtc-ims/blob/main/app/Models/Patient.php"
click node_inventory "https://github.com/juls-33/rbtc-ims/blob/main/app/Models/MedicineCatalog.php"
click node_billing "https://github.com/juls-33/rbtc-ims/blob/main/app/Models/OutpatientBillItem.php"
click node_staff "https://github.com/juls-33/rbtc-ims/blob/main/app/Models/Staff.php"
click node_migrations "https://github.com/juls-33/rbtc-ims/blob/main/database/migrations/2026_01_09_122923_create_patients_table.php"
click node_db "https://github.com/juls-33/rbtc-ims/blob/main/config/database.php"
click node_ciphersweet "https://github.com/juls-33/rbtc-ims/blob/main/config/ciphersweet.php"
click node_invoices "https://github.com/juls-33/rbtc-ims/blob/main/resources/views/inpatient_invoice.blade.php"

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_browser,node_spa_shell,node_role_pages,node_shared_ui toneBlue
class node_public_index,node_web_routes,node_auth_routes,node_controllers,node_auth_controllers,node_inertia,node_guards toneAmber
class node_patient_ops,node_inventory,node_billing,node_staff toneMint
class node_migrations,node_db,node_ciphersweet toneRose
class node_invoices toneIndigo
```

## Components

### Client

Browser and React/Inertia frontend

- **Browser**: ui client · Users access the SPA and server-rendered pages here
- [SPA shell](https://github.com/juls-33/rbtc-ims/blob/main/resources/js/app.jsx): react entry · Client bootstrap for the Inertia app · `resources/js/app.jsx`
- [Role pages](https://github.com/juls-33/rbtc-ims/blob/main/resources/js/Pages/Admin/PatientManagement.jsx): react pages · Admin, doctor, and nurse screens · `resources/js/Pages/Admin/PatientManagement.jsx`
- [Shared UI](https://github.com/juls-33/rbtc-ims/blob/main/resources/js/Components/Modal.jsx): react components · Reusable modals, tables, inputs, and layout primitives · `resources/js/Components/Modal.jsx`

### HTTP App

Laravel entrypoint, routing, controllers, and middleware

- [Entry](https://github.com/juls-33/rbtc-ims/blob/main/public/index.php): php front controller · HTTP bootstrap for all web requests · `public/index.php`
- [Web routes](https://github.com/juls-33/rbtc-ims/blob/main/routes/web.php): route map · Main application routing for the monolith · `routes/web.php`
- [Auth routes](https://github.com/juls-33/rbtc-ims/blob/main/routes/auth.php): route map · Authentication and verification routes · `routes/auth.php`
- [Controllers](https://github.com/juls-33/rbtc-ims/blob/main/app/Http/Controllers/DashboardController.php): web controllers · Primary application controllers for patient, staff, room, and billing flows · `app/Http/Controllers/DashboardController.php`
- [Auth flow](https://github.com/juls-33/rbtc-ims/blob/main/app/Http/Controllers/Auth/AuthenticatedSessionController.php): auth controllers · Login, registration, reset, verification, and password controls · `app/Http/Controllers/Auth/AuthenticatedSessionController.php`
- [Inertia bridge](https://github.com/juls-33/rbtc-ims/blob/main/app/Http/Middleware/HandleInertiaRequests.php): middleware · Bridges Laravel responses to React page rendering · `app/Http/Middleware/HandleInertiaRequests.php`
- [Access guards](https://github.com/juls-33/rbtc-ims/blob/main/app/Http/Middleware/DoctorMiddleware.php): middleware · Role, account-status, and forced-password-change checks · `app/Http/Middleware/DoctorMiddleware.php`

### Domain

Core patient, inventory, billing, and staff workflows

- [Patient ops](https://github.com/juls-33/rbtc-ims/blob/main/app/Models/Patient.php): domain workflow · Patients, admissions, visits, logs, and archives · `app/Models/Patient.php`
- [Inventory](https://github.com/juls-33/rbtc-ims/blob/main/app/Models/MedicineCatalog.php): domain workflow · Medicine catalogs, batches, stock logs, and medication logs · `app/Models/MedicineCatalog.php`
- [Billing](https://github.com/juls-33/rbtc-ims/blob/main/app/Models/OutpatientBillItem.php): domain workflow · Outpatient and inpatient billing flows · `app/Models/OutpatientBillItem.php`
- [Staff identity](https://github.com/juls-33/rbtc-ims/blob/main/app/Models/Staff.php): security domain · Staff accounts, logs, and identity state · `app/Models/Staff.php`

### Data

Database schema, persistence, and encryption support

- [Migrations](https://github.com/juls-33/rbtc-ims/blob/main/database/migrations/2026_01_09_122923_create_patients_table.php): schema evolution · Database schema and relationship history · `database/migrations/2026_01_09_122923_create_patients_table.php`
- [MySQL](https://github.com/juls-33/rbtc-ims/blob/main/config/database.php): database · Primary relational datastore · `config/database.php`
- [CipherSweet](https://github.com/juls-33/rbtc-ims/blob/main/config/ciphersweet.php): encryption config · Encrypted and searchable data support · `config/ciphersweet.php`

### Output

Server-rendered documents

- [Invoices](https://github.com/juls-33/rbtc-ims/blob/main/resources/views/inpatient_invoice.blade.php): blade views · Printable inpatient and outpatient invoice templates · `resources/views/inpatient_invoice.blade.php`

## Connections

- Browser → Entry: requests · Browser traffic enters the Laravel front controller
- Entry → Web routes: dispatches · Web requests are routed through the main route table
- Entry → Auth routes: auth dispatch · Authentication requests are routed separately
- Web routes → Controllers: handles · Controllers implement the main application flows
- Auth routes → Auth flow: handles · Auth controllers manage login and account recovery
- Controllers → Access guards: protected by · Role and status middleware gate sensitive actions
- Auth flow → Access guards: checks · Auth lifecycle is constrained by account and password rules
- Controllers → Inertia bridge: renders · Controllers return Inertia responses into the React UI
- Inertia bridge → SPA shell: bootstraps · Inertia hydrates the client entrypoint
- SPA shell → Role pages: loads · Role-specific pages provide the main UI slices
- SPA shell → Shared UI: composes · Shared components and layouts are reused across pages
- Role pages → Controllers: actions · Page interactions submit back to Laravel controllers
- Controllers → Patient ops: orchestrates · Patient admissions, visits, logs, and archives are coordinated server-side
- Controllers → Inventory: orchestrates · Medicine and stock management flows pass through controllers
- Controllers → Billing: orchestrates · Billing and invoice generation are handled in the backend
- Controllers → Staff identity: manages · Staff management and operational history are part of the domain
- Patient ops → Migrations: persisted by · Patient workflow data is defined by schema migrations
- Inventory → Migrations: persisted by · Inventory tables and logs are created and evolved in migrations
- Billing → Migrations: persisted by · Billing tables and redesigns are captured in migrations
- Staff identity → Migrations: persisted by · Staff identity and security fields evolve through migrations
- Migrations → MySQL: applies to · Migrations define the MySQL schema
- Staff identity → CipherSweet: secured by · Encrypted/searchable staff data depends on CipherSweet support
- Billing → Invoices: prints · Billing records can be rendered into Blade invoice documents
