How debottam20/carequeue works
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: Models Core models · web.php Web routes · Commands Console jobs · Notifications Notifications
Components 24
HTTP layer
Controllers, middleware, request validation, and route entrypoints for web interactions.
- Web routes · Main web route surface for public, patient, and admin flows.
routes/web.php - Auth routes · Breeze authentication route surface.
routes/auth.php - Admin guard · Protects admin-only access.
app/Http/Middleware/AdminMiddleware.php - Auth flows · Registration, login, password reset, verification, and session lifecycle.
app/Http/Controllers/Auth - Profile · Profile update, password change, and account deletion flows.
app/Http/Controllers/ProfileController.php - Admin panel · Admin dashboard and high-level management entrypoint.
app/Http/Controllers/AdminController.php - Doctors · Create, edit, and delete doctors from the admin area.
app/Http/Controllers/DoctorController.php - Patients · Patient-facing calendar/booking plus admin patient management.
app/Http/Controllers/PatientController.php - Appointments · 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 · User, Patient, Doctor, TimeSlot, and Appointment domain entities.
app/Models - ID reuse · Reusable concern for restoring deleted ID sequences.
app/Models/Concerns/ReusesDeletedIds.php - Phone rules · Shared 10-digit phone validation logic.
app/Validation/PhoneRules.php - Schema · Tables and schema evolution for users, doctors, patients, appointments, and time slots.
database/migrations - Seed data · Bootstraps initial admin and sample doctor data.
database/seeders/DatabaseSeeder.php
UI layer
Blade views, layouts, components, and frontend assets.
- Patient views · Calendar and appointment pages for patients.
resources/views/patient - Admin views · Dashboard plus doctor, patient, and appointment management screens.
resources/views/admin - Layouts · Shared application and guest shells plus navigation chrome.
resources/views/layouts - Components · Reusable UI primitives and form controls.
resources/views/components - Report views · Templates used to generate PDF reports.
resources/views/reports - Frontend 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 · Email side effects for welcome, booking, cancellation, profile, password, and deletion events.
app/Notifications - Console jobs · Scheduled maintenance, completion, sync, and PDF generation tasks.
app/Console/Commands - Config · Application, cache, database, mail, queue, and session settings.
config - Scheduler · Defines scheduled command execution.
routes/console.php
Connections 29
- 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.