How boufarra-oussama/admin_backend works
1. This repository is a Laravel-based backend API for a medical records and clinic operations system. It is not primarily a web UI app; the main surface area is routes/api.php plus supporting console jobs, mail, notifications, and PDF generation.
2. The core architectural pattern is layered: API controllers handle HTTP concerns, FormRequest classes validate input, Service classes contain business logic, Repository classes abstract persistence for some domains, and Eloquent models map to the database. RepositoryServiceProvider binds interfaces to implementations.
3. Authentication is token-based and appears to use JWT as the main API auth mechanism. The auth flow is centered on AuthController, JwtMiddleware, JwtTokenService, and the jwt_tokens table. The README also shows login/refresh/logout/me endpoints, so token lifecycle is a distinct subsystem.
4. Authorization is role/permission driven. Roles and permissions are first-class models with pivot tables, and PermissionMiddleware enforces access on protected routes. The README documents protected operations such as user management, role management, bill management, and analytics access via permissions like roles:view and bills:manage.
5. The system’s major business domains are users, patients, doctors, appointments, billing, medical records, reminders, analytics, and activity logs. These are each separated into dedicated controllers and services, which suggests the API is organized by domain rather than by technical layer only.
6. Medical record handling is its own subsystem. Models such as MedicalHistory, VitalSign, LabResult, PatientFile, PatientNote, PatientAlert, TimelineEvent, and file/notification services indicate a patient-centered record timeline with uploads, alerts, and lifecycle tracking. Observers and notification services support side effects when records or profile data change.
7. Appointment management is split across general, doctor-facing, and patient-facing flows. AppointmentService, DoctorAppointmentController, PatientAppointmentController, AppointmentObserver, and reminder jobs suggest appointments are a central workflow with scheduling rules, blocked slots, and downstream reminder generation.
8. Billing and finance is another major bounded context. BillController, BillService, BillItem/Bill models, bill resources, PDF views, and dompdf config indicate bills can be created, filtered, itemized, exported, and downloaded as PDFs. The README also shows patient read-only bill access and staff-only management, so billing has role-specific access paths.
9. Reminders are implemented as an async subsystem. ScheduleAppointmentReminders, SendAppointmentReminder, and CancelScheduledReminders jobs, plus reminder settings/logs/analytics tables, show a queue-backed reminder engine. Email templates under resources/views/emails/reminders and AppointmentReminderMail indicate reminders are delivered through mail, with custom notification channels also available for SMS and push.
10. Analytics is service-oriented and reads aggregated data from operational tables. AnalyticsService, FinancialAnalyticsService, DateFilterService, and analytics controllers provide reporting for users, revenue, services, and doctor revenue. The README’s export endpoint suggests some analytics can be downloaded, likely as CSV.
11. Activity logging is pervasive and cross-cutting. ActivityLogger middleware, ActivityLog model/repository/service, and the Spatie activitylog setup referenced in the README indicate audit trails are recorded across sensitive operations such as authentication, CRUD actions, and billing. This is a system-wide observability boundary, not just a feature module.
12. AI diagnostic support is present as a separate capability. AiDiagnosticController, AiDiagnosticService, and AiAnalysis/AiModel models indicate the app can run or store AI-based medical analysis results. This appears integrated into the medical domain rather than exposed as a standalone product.
13. The data layer is explicitly modeled in migrations and seeders. The schema includes users, roles, permissions, appointments, patients, doctors, bills, medical records, reminders, notifications, and logs, with many junction tables for RBAC and AI model assignment. Seeders provide initial roles, permissions, test patients/doctors, appointments, and reminder data.
14. Infrastructure concerns are built into the repo. There are Docker images for multiple PHP versions, database scripts for PostgreSQL/MySQL/MariaDB, queue worker startup scripts, and Laravel queue/cache/session configs. This means the app expects database, queue, mail, and file-storage services to be part of the runtime architecture.
15. The main request flow is: API request enters Laravel, passes through JWT and permission middleware, hits a domain controller, validates with a FormRequest, executes service logic, optionally uses a repository, writes to Eloquent models/database, then emits side effects such as audit logs, notifications, queued jobs, email, or PDFs. That pipeline is the most important diagram boundary for this repo.
Main entry points: api.php API routes · Models Domain models · AuthController.php Auth · JwtTokenService.php Token service
Components 23
API layer
HTTP entrypoints, middleware, controllers, and request validation
- API routes · Main HTTP surface for the backend API
routes/api.php - Auth · Login, refresh, logout, and current-user endpoints
app/Http/Controllers/Api/AuthController.php - Clinic APIs · Controllers for users, patients, doctors, appointments, billing, records, analytics, and reminders
- Form requests · Input validation for auth, billing, patients, roles, reminders, analytics, and personal data
app/Http/Requests
Domain services
Core clinic workflows and business logic
- Auth service · Coordinates credential checks and session state
app/Services/AuthService.php - Token service · Creates, refreshes, and revokes API tokens
app/Services/JwtTokenService.php - Access control · Users, roles, permissions, and profile management
app/Services/UserService.php - Appointments · Scheduling logic for clinic appointments and doctor/patient flows
app/Services/AppointmentService.php - Medical records · Patient file timeline, notes, alerts, vitals, lab results, and uploads
app/Services/Medical/PatientMedicalDataService.php - Billing · Bill creation, itemization, filtering, and export support
app/Services/BillService.php - Reminders · Reminder settings, scheduling, cancellation, and delivery coordination
app/Services/ReminderService.php - Analytics · Aggregated reporting for users, revenue, doctors, and services
app/Services/AnalyticsService.php - Activity logs · Audit trail capture and retrieval across sensitive operations
app/Services/ActivityLogService.php - AI diagnostics · Medical AI analysis execution and persistence
app/Services/AiDiagnosticService.php
Data layer
Models, repositories, schema, and persistence bindings
- Repo bindings · Binds repository interfaces to Eloquent implementations
app/Providers/RepositoryServiceProvider.php - Repositories · Eloquent repository implementations for selected domains
app/Repositories - Domain models · Core entities for users, patients, doctors, appointments, bills, records, roles, permissions, tokens, reminders, and logs
app/Models - Schema data · Database schema, pivots, indexes, and bootstrap data
database
Async side effects
Jobs, mail, notifications, and document rendering
- Async side effects · Queued reminders, mail delivery, and patient-file notifications
app/Jobs - PDF templates · Bill and receipt templates used for downloadable PDFs
resources/views/pdfs
Cross-cutting
Authentication, authorization, and audit concerns
- JWT middleware · Token authentication guard for protected API routes
app/Http/Middleware/JwtMiddleware.php - Permission guard · Role and permission enforcement on protected operations
app/Http/Middleware/PermissionMiddleware.php - Activity logger · Cross-cutting audit capture for sensitive actions
app/Http/Middleware/ActivityLogger.php
Connections 31
- API routes → JWT middleware: protects · Protected API routes pass through token authentication
- API routes → Permission guard: authorizes · Sensitive endpoints are gated by permissions
- API routes → Activity logger: audits · Selected operations are captured for audit trails
- API routes → Auth: auth endpoints · Login and token lifecycle endpoints
- API routes → Clinic APIs: domain endpoints · Primary controllers for clinic operations
- Auth → Form requests: validates · Auth requests are validated before processing
- Clinic APIs → Form requests: validates · Controllers use FormRequest classes for input checks
- Auth → Auth service: uses · Delegates credential and session handling
- Auth service → Token service: issues tokens · Auth service relies on token lifecycle logic
- Token service → Domain models: stores · JWT token state is persisted in the data layer
- Clinic APIs → Access control: uses · User, role, permission, and profile flows
- Clinic APIs → Appointments: uses · Appointment creation, updates, and scheduling
- Clinic APIs → Medical records: uses · Medical history, files, notes, alerts, and lab data
- Clinic APIs → Billing: uses · Billing CRUD and export operations
- Clinic APIs → Reminders: uses · Reminder setup and bulk operations
- Clinic APIs → Analytics: uses · Reporting and export endpoints
- Clinic APIs → Activity logs: uses · Audit log access and admin views
- Clinic APIs → AI diagnostics: uses · AI-assisted diagnostic endpoints
- Permission guard → Access control: enforces · Protected operations depend on roles and permissions
- Activity logger → Activity logs: writes · Audit middleware feeds the activity log subsystem
- Access control → Repo bindings: resolves via · Repository interfaces are injected through the provider
- Repo bindings → Repositories: maps to · Interface implementations are wired here
- Repositories → Domain models: persists · Repository layer wraps Eloquent persistence
- Appointments → Async side effects: queues reminders · Appointments trigger scheduled reminders and notifications
- Medical records → Async side effects: notifies · Patient file and record changes emit notifications
- Billing → PDF templates: renders PDFs · Bills and receipts can be exported as PDF documents
- Analytics → Schema data: reads aggregates · Reporting is driven by operational tables and seeded data
- Activity logs → Domain models: writes audits · Activity logging is stored centrally
- Async side effects → Domain models: updates status · Reminder jobs and notifications record lifecycle state
- Schema data → Domain models: defines schema · Tables and seed data shape the model layer
- JWT middleware → Token service: verifies · Incoming requests are checked against token lifecycle state