# debottam20/carequeue architecture

> Architecture diagram of the GitHub repository debottam20/carequeue, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/debottam20/carequeue
- Repository: https://github.com/debottam20/carequeue

## Overview

1. **Overall shape**
   - CareQueue is a monolithic Laravel 12 application with a classic server-rendered MVC structure.
   - The main boundaries are `Http\Controllers` for request handling, `Models` for domain state, `resources/views` for UI, and `Notifications`/`Console\Commands` for side effects and scheduled work.

2. **User roles and access model**
   - The system is built around two interactive roles: **admin** and **patient**.
   - Admin access is enforced by `app/Http/Middleware/AdminMiddleware.php`.
   - Doctors are part of the domain but do **not** authenticate into the app; they are passive recipients of email notifications.

3. **Authentication and profile subsystem**
   - Authentication is handled by Laravel Breeze controllers under `app/Http/Controllers/Auth`.
   - This includes registration, login, password reset, email verification, and profile management.
   - Profile update and password change flows are backed by `ProfileController` and request validation classes like `ProfileUpdateRequest` and `LoginRequest`.

4. **Core domain model**
   - The central entities are `User`, `Patient`, `Doctor`, `TimeSlot`, and `Appointment`.
   - `User` likely represents authenticated accounts, with role data stored on the users table.
   - `Doctor` and `Patient` are separate business entities, while `Appointment` links patients to doctors at a chosen date/time.
   - `TimeSlot` represents recurring availability rules for doctors rather than booked appointments.

5. **Appointment scheduling flow**
   - Patients browse availability through `PatientController` and the calendar views in `resources/views/patient`.
   - Availability is derived from doctor time slots plus date-specific logic, with past same-day slots hidden.
   - Booking is handled by `AppointmentController`, which must enforce conflict prevention so the same doctor/date/time cannot be double-booked.
   - Appointment status is lifecycle-driven: `pending`, `confirmed`, `cancelled`, `completed`.

6. **Admin management subsystem**
   - `AdminController`, `DoctorController`, and `PatientController` power the admin area under `resources/views/admin`.
   - Admins can create/edit/delete doctors, maintain patients, inspect all appointments, and view dashboard metrics.
   - The dashboard aggregates counts for active doctors, patients, confirmed appointments, and today’s schedule, so it acts as a read-only summary view over the domain tables.

7. **Notifications and email side effects**
   - Business events emit email notifications through Laravel notifications in `app/Notifications`.
   - Important events include patient welcome, booking confirmation, cancellation notices to both patient and doctor, profile updates, password changes, and account deletion.
   - In local development, mail is logged instead of sent, so the app has a low-friction dev loop without external SMTP dependence.

8. **Background and scheduled processing**
   - The app includes console commands in `app/Console/Commands` for recurring maintenance and report generation.
   - `appointments:complete-past` is the key scheduled job: it marks past confirmed/pending appointments as completed, and the README says it runs every five minutes via the scheduler.
   - `ids:sync` is a data maintenance utility that resets auto-increment sequences to reuse deleted IDs.

9. **Reporting and document generation**
   - Two artisan commands generate PDF artifacts: a project report and an API-endpoints report.
   - These use Blade report templates under `resources/views/reports` and the `barryvdh/laravel-dompdf` integration.
   - The generated PDFs are checked into `docs/`, which makes documentation part of the repository output, not just the runtime app.

10. **Frontend composition**
   - The UI is Blade-based with reusable layout components in `resources/views/layouts` and `resources/views/components`.
   - Styling and client-side behavior are built with Tailwind CSS, Alpine.js, and Vite.
   - There is a small custom JavaScript asset for phone-number input behavior, indicating some client-side formatting/validation support without a heavy SPA architecture.

11. **Validation and shared business rules**
   - Shared validation logic lives in `app/Validation`, including `PhoneRules.php` for 10-digit phone constraints.
   - Request classes and validation rules are used to centralize input checks for auth and profile flows.
   - The existence of reusable validation and model concerns like `ReusesDeletedIds` suggests the app keeps business rules close to the domain layer rather than scattering them across controllers.

12. **Persistence and schema evolution**
   - The database is migration-driven, with clear historical changes for doctors, appointments, time slots, patients, role support, and phone normalization.
   - Separate migrations also show schema refactoring over time, such as restructuring the patients table and dropping an appointment uniqueness constraint.
   - Seeders create initial admin and sample doctor data, which means the app expects a non-empty operational dataset from first boot.

13. **Operational boundaries**
   - The app depends on standard Laravel infrastructure: cache, queue, session, logging, and mail configuration in `config/`.
   - `routes/web.php` and `routes/auth.php` divide public/authenticated app routes from the Breeze auth surface.
   - A health endpoint at `/up` supports deployment monitoring, and queue/scheduler settings are present even though much of the work is request-driven.

14. **Testing scope**
   - Pest-based tests focus on authentication, registration, profile management, and password flows.
   - This indicates the most test-covered boundary is user account lifecycle, while the domain-heavy scheduling logic is likely validated more by application flow than exhaustive unit coverage.

15. **Architecture diagram takeaway**
   - If drawing the system, place the browser/UI on one side, routed into Laravel controllers in the middle, with models and database beneath.
   - Attach notifications/email and scheduled commands as side-effect subsystems off the core appointment and account workflows.
   - Keep admin and patient paths separate at the controller/view layer, while sharing the same underlying appointment and availability data model.

Main entry points: [`app/Models`](https://github.com/debottam20/carequeue/tree/main/app/Models) (Core models), [`routes/web.php`](https://github.com/debottam20/carequeue/blob/main/routes/web.php) (Web routes), [`app/Console/Commands`](https://github.com/debottam20/carequeue/tree/main/app/Console/Commands) (Console jobs), [`app/Notifications`](https://github.com/debottam20/carequeue/tree/main/app/Notifications) (Notifications)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_http["HTTP layer"]
  node_node_web_routes["Web routes<br/>route map<br/>[web.php]"]
  node_node_auth_routes["Auth routes<br/>route map<br/>[auth.php]"]
  node_node_admin_mw["Admin guard<br/>middleware"]
  node_node_auth_ctrls["Auth flows<br/>Breeze controllers"]
  node_node_profile_ctrl["Profile<br/>account controller"]
  node_node_admin_ctrl["Admin panel<br/>dashboard controller"]
  node_node_doctor_ctrl["Doctors<br/>admin controller"]
  node_node_patient_ctrl["Patients<br/>hybrid controller"]
  node_node_appt_ctrl["Appointments<br/>scheduling controller"]
end

subgraph group_group_domain["Domain & data"]
  node_node_models[("Core models<br/>Eloquent models")]
  node_node_reuse_ids["ID reuse<br/>model concern"]
  node_node_phone_rules["Phone rules<br/>validation rules<br/>[PhoneRules.php]"]
  node_node_migrations["Schema<br/>migrations"]
  node_node_seeders["Seed data<br/>seeders<br/>[DatabaseSeeder.php]"]
end

subgraph group_group_ui["UI layer"]
  node_node_patient_views["Patient views<br/>Blade views"]
  node_node_admin_views["Admin views<br/>Blade views"]
  node_node_layouts["Layouts"]
  node_node_components["Components"]
  node_node_reports["Report views<br/>Blade templates"]
  node_node_frontend["Frontend assets<br/>Tailwind/Vite assets<br/>[app.js]"]
end

subgraph group_group_ops["Background & ops"]
  node_node_notifications["Notifications"]
  node_node_commands["Console jobs<br/>artisan commands"]
  node_node_config["Config"]
  node_node_scheduler["Scheduler<br/>console routes<br/>[console.php]"]
end

node_node_web_routes -->|"includes auth surface"| node_node_auth_routes
node_node_web_routes -->|"guards admin area"| node_node_admin_mw
node_node_web_routes -->|"dispatches"| node_node_admin_ctrl
node_node_web_routes -->|"dispatches"| node_node_doctor_ctrl
node_node_web_routes -->|"dispatches"| node_node_patient_ctrl
node_node_web_routes -->|"dispatches"| node_node_appt_ctrl
node_node_auth_routes -->|"dispatches"| node_node_auth_ctrls
node_node_auth_ctrls -->|"authenticates users"| node_node_models
node_node_profile_ctrl -->|"updates profile"| node_node_models
node_node_profile_ctrl -->|"emits account notices"| node_node_notifications
node_node_admin_ctrl -->|"summarizes data"| node_node_models
node_node_doctor_ctrl -->|"manages doctors"| node_node_models
node_node_patient_ctrl -->|"reads patients"| node_node_models
node_node_appt_ctrl -->|"books appointments"| node_node_models
node_node_appt_ctrl -->|"sends booking alerts"| node_node_notifications
node_node_models -->|"persisted by"| node_node_migrations
node_node_models -->|"uses concern"| node_node_reuse_ids
node_node_models -->|"validates phones"| node_node_phone_rules
node_node_seeders -->|"seeds schema"| node_node_migrations
node_node_patient_views -->|"extends"| node_node_layouts
node_node_admin_views -->|"extends"| node_node_layouts
node_node_admin_views -->|"uses"| node_node_components
node_node_patient_views -->|"uses"| node_node_components
node_node_reports -->|"rendered by"| node_node_commands
node_node_frontend -->|"enhances forms"| node_node_components
node_node_commands -->|"scheduled by"| node_node_scheduler
node_node_commands -.->|"can trigger"| node_node_notifications
node_node_config -->|"configures mail"| node_node_notifications
node_node_config -->|"configures queue"| node_node_commands

click node_node_web_routes "https://github.com/debottam20/carequeue/blob/main/routes/web.php"
click node_node_auth_routes "https://github.com/debottam20/carequeue/blob/main/routes/auth.php"
click node_node_admin_mw "https://github.com/debottam20/carequeue/blob/main/app/Http/Middleware/AdminMiddleware.php"
click node_node_auth_ctrls "https://github.com/debottam20/carequeue/tree/main/app/Http/Controllers/Auth"
click node_node_profile_ctrl "https://github.com/debottam20/carequeue/blob/main/app/Http/Controllers/ProfileController.php"
click node_node_admin_ctrl "https://github.com/debottam20/carequeue/blob/main/app/Http/Controllers/AdminController.php"
click node_node_doctor_ctrl "https://github.com/debottam20/carequeue/blob/main/app/Http/Controllers/DoctorController.php"
click node_node_patient_ctrl "https://github.com/debottam20/carequeue/blob/main/app/Http/Controllers/PatientController.php"
click node_node_appt_ctrl "https://github.com/debottam20/carequeue/blob/main/app/Http/Controllers/AppointmentController.php"
click node_node_models "https://github.com/debottam20/carequeue/tree/main/app/Models"
click node_node_reuse_ids "https://github.com/debottam20/carequeue/blob/main/app/Models/Concerns/ReusesDeletedIds.php"
click node_node_phone_rules "https://github.com/debottam20/carequeue/blob/main/app/Validation/PhoneRules.php"
click node_node_migrations "https://github.com/debottam20/carequeue/tree/main/database/migrations"
click node_node_seeders "https://github.com/debottam20/carequeue/blob/main/database/seeders/DatabaseSeeder.php"
click node_node_patient_views "https://github.com/debottam20/carequeue/tree/main/resources/views/patient"
click node_node_admin_views "https://github.com/debottam20/carequeue/tree/main/resources/views/admin"
click node_node_layouts "https://github.com/debottam20/carequeue/tree/main/resources/views/layouts"
click node_node_components "https://github.com/debottam20/carequeue/tree/main/resources/views/components"
click node_node_reports "https://github.com/debottam20/carequeue/tree/main/resources/views/reports"
click node_node_frontend "https://github.com/debottam20/carequeue/blob/main/resources/js/app.js"
click node_node_notifications "https://github.com/debottam20/carequeue/tree/main/app/Notifications"
click node_node_commands "https://github.com/debottam20/carequeue/tree/main/app/Console/Commands"
click node_node_config "https://github.com/debottam20/carequeue/tree/main/config"
click node_node_scheduler "https://github.com/debottam20/carequeue/blob/main/routes/console.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_node_web_routes,node_node_auth_routes,node_node_admin_mw,node_node_auth_ctrls,node_node_profile_ctrl,node_node_admin_ctrl,node_node_doctor_ctrl,node_node_patient_ctrl,node_node_appt_ctrl toneBlue
class node_node_models,node_node_reuse_ids,node_node_phone_rules,node_node_migrations,node_node_seeders toneAmber
class node_node_patient_views,node_node_admin_views,node_node_layouts,node_node_components,node_node_reports,node_node_frontend toneMint
class node_node_notifications,node_node_commands,node_node_config,node_node_scheduler toneRose
```

## Components

### HTTP layer

Controllers, middleware, request validation, and route entrypoints for web interactions.

- [Web routes](https://github.com/debottam20/carequeue/blob/main/routes/web.php): route map · Main web route surface for public, patient, and admin flows. · `routes/web.php`
- [Auth routes](https://github.com/debottam20/carequeue/blob/main/routes/auth.php): route map · Breeze authentication route surface. · `routes/auth.php`
- [Admin guard](https://github.com/debottam20/carequeue/blob/main/app/Http/Middleware/AdminMiddleware.php): middleware · Protects admin-only access. · `app/Http/Middleware/AdminMiddleware.php`
- [Auth flows](https://github.com/debottam20/carequeue/tree/main/app/Http/Controllers/Auth): Breeze controllers · Registration, login, password reset, verification, and session lifecycle. · `app/Http/Controllers/Auth`
- [Profile](https://github.com/debottam20/carequeue/blob/main/app/Http/Controllers/ProfileController.php): account controller · Profile update, password change, and account deletion flows. · `app/Http/Controllers/ProfileController.php`
- [Admin panel](https://github.com/debottam20/carequeue/blob/main/app/Http/Controllers/AdminController.php): dashboard controller · Admin dashboard and high-level management entrypoint. · `app/Http/Controllers/AdminController.php`
- [Doctors](https://github.com/debottam20/carequeue/blob/main/app/Http/Controllers/DoctorController.php): admin controller · Create, edit, and delete doctors from the admin area. · `app/Http/Controllers/DoctorController.php`
- [Patients](https://github.com/debottam20/carequeue/blob/main/app/Http/Controllers/PatientController.php): hybrid controller · Patient-facing calendar/booking plus admin patient management. · `app/Http/Controllers/PatientController.php`
- [Appointments](https://github.com/debottam20/carequeue/blob/main/app/Http/Controllers/AppointmentController.php): scheduling controller · Booking, conflict checks, and appointment lifecycle actions. · `app/Http/Controllers/AppointmentController.php`

### Domain & data

Core entities, reusable model concerns, validation rules, and database schema.

- [Core models](https://github.com/debottam20/carequeue/tree/main/app/Models): Eloquent models · User, Patient, Doctor, TimeSlot, and Appointment domain entities. · `app/Models`
- [ID reuse](https://github.com/debottam20/carequeue/blob/main/app/Models/Concerns/ReusesDeletedIds.php): model concern · Reusable concern for restoring deleted ID sequences. · `app/Models/Concerns/ReusesDeletedIds.php`
- [Phone rules](https://github.com/debottam20/carequeue/blob/main/app/Validation/PhoneRules.php): validation rules · Shared 10-digit phone validation logic. · `app/Validation/PhoneRules.php`
- [Schema](https://github.com/debottam20/carequeue/tree/main/database/migrations): migrations · Tables and schema evolution for users, doctors, patients, appointments, and time slots. · `database/migrations`
- [Seed data](https://github.com/debottam20/carequeue/blob/main/database/seeders/DatabaseSeeder.php): seeders · Bootstraps initial admin and sample doctor data. · `database/seeders/DatabaseSeeder.php`

### UI layer

Blade views, layouts, components, and frontend assets.

- [Patient views](https://github.com/debottam20/carequeue/tree/main/resources/views/patient): Blade views · Calendar and appointment pages for patients. · `resources/views/patient`
- [Admin views](https://github.com/debottam20/carequeue/tree/main/resources/views/admin): Blade views · Dashboard plus doctor, patient, and appointment management screens. · `resources/views/admin`
- [Layouts](https://github.com/debottam20/carequeue/tree/main/resources/views/layouts): Blade layouts · Shared application and guest shells plus navigation chrome. · `resources/views/layouts`
- [Components](https://github.com/debottam20/carequeue/tree/main/resources/views/components): Blade components · Reusable UI primitives and form controls. · `resources/views/components`
- [Report views](https://github.com/debottam20/carequeue/tree/main/resources/views/reports): Blade templates · Templates used to generate PDF reports. · `resources/views/reports`
- [Frontend assets](https://github.com/debottam20/carequeue/blob/main/resources/js/app.js): Tailwind/Vite assets · CSS, JavaScript, and phone-input behavior for the server-rendered UI. · `resources/js/app.js`

### Background & ops

Notifications, console jobs, scheduling, reports, and runtime configuration.

- [Notifications](https://github.com/debottam20/carequeue/tree/main/app/Notifications): Laravel notifications · Email side effects for welcome, booking, cancellation, profile, password, and deletion events. · `app/Notifications`
- [Console jobs](https://github.com/debottam20/carequeue/tree/main/app/Console/Commands): artisan commands · Scheduled maintenance, completion, sync, and PDF generation tasks. · `app/Console/Commands`
- [Config](https://github.com/debottam20/carequeue/tree/main/config): runtime config · Application, cache, database, mail, queue, and session settings. · `config`
- [Scheduler](https://github.com/debottam20/carequeue/blob/main/routes/console.php): console routes · Defines scheduled command execution. · `routes/console.php`

## Connections

- Web routes → Auth routes: includes auth surface · Public web routing is separated from Breeze authentication routes.
- Web routes → Admin guard: guards admin area · Admin-only routes are protected by middleware.
- Web routes → Admin panel: dispatches · Routes reach the admin dashboard controller.
- Web routes → Doctors: dispatches · Routes reach doctor management actions.
- Web routes → Patients: dispatches · Routes reach patient-facing and admin patient actions.
- Web routes → Appointments: dispatches · Routes reach appointment booking and lifecycle actions.
- Auth routes → Auth flows: dispatches · Authentication routes are handled by Breeze controllers.
- Auth flows → Core models: authenticates users · Registration and login operate on user accounts.
- Profile → Core models: updates profile · Profile edits and password changes persist through the user model.
- Profile → Notifications: emits account notices · Profile and password changes trigger email notifications.
- Admin panel → Core models: summarizes data · Dashboard aggregates counts from core tables.
- Doctors → Core models: manages doctors · Doctor CRUD acts on domain models and persistence.
- Patients → Core models: reads patients · Patient management and calendar views read from domain state.
- Appointments → Core models: books appointments · Scheduling logic reads availability and writes appointments.
- Appointments → Notifications: sends booking alerts · Appointment events notify patients and doctors.
- Core models → Schema: persisted by · Models are backed by the database schema.
- Core models → ID reuse: uses concern · Some models reuse deleted IDs through a shared concern.
- Core models → Phone rules: validates phones · Phone constraints are shared across domain forms.
- Seed data → Schema: seeds schema · Seed data depends on the migrated tables.
- Patient views → Layouts: extends · Patient screens share application shells.
- Admin views → Layouts: extends · Admin screens share application shells.
- Admin views → Components: uses · Admin screens reuse form and navigation components.
- Patient views → Components: uses · Patient screens reuse shared components.
- Report views → Console jobs: rendered by · PDF report commands use Blade templates.
- Frontend assets → Components: enhances forms · Client-side behavior supports shared UI components.
- Console jobs → Scheduler: scheduled by · Recurring jobs are registered with the scheduler.
- Console jobs → Notifications: can trigger · Background tasks can produce user-facing email side effects.
- Config → Notifications: configures mail · Mail transport and environment settings govern delivery.
- Config → Console jobs: configures queue · Console and queue settings support background execution.
