jennymph/tt-web-backend

1. What this repository is

- TT-Web is a Laravel-based REST backend for managing the “proceso de protocolos” at ESCOM.

- The architecture is server-side focused: HTTP APIs, database persistence, email delivery, and a small set of Blade views for mail/templates and public pages.

2. Top-level application boundary

- The application follows the standard Laravel split: routes receive requests, app/Http/Controllers orchestrate logic, app/Models map to the database, and database/migrations define the schema.

- The main runtime boundary is the Laravel HTTP kernel plus middleware stack, with an additional CLI boundary through artisan and console kernel.

3. Primary business areas

- The codebase centers on a few domain objects:

- User for authentication and account management

- Student

- Staff

- Protocol

- DatesAndTerms

- Consulta for contact/help inquiries

- These suggest the backend coordinates users and academic protocol records, with time/term configuration as a separate concern.

4. HTTP/API layer

- Controllers in app/Http/Controllers are the main entry points:

- AuthController

- UsersController

- StudentController

- StaffController

- ProtocolController

- DatesAndTermsController

- VerifyMail

- Routes are split between routes/web.php and routes/api.php, so the app likely serves both browser-facing pages and API endpoints.

5. Authentication and session/token handling

- Auth is reinforced by Laravel middleware and config, including Authenticate, RedirectIfAuthenticated, UpdateTokenExpiry, and ValidateSignature.

- config/sanctum.php and personal_access_tokens migration indicate Laravel Sanctum is used for API authentication/token access.

- config/session.php and the standard Laravel auth scaffolding suggest some routes may still rely on session-based behavior for web flows.

6. Persistence and database model

- Database structure is defined entirely through migrations, including users, students, staff, protocols, consultas, and dates/terms.

- There is a migration to enable PostgreSQL extensions, which strongly suggests PostgreSQL is the primary database.

- Eloquent models mirror the tables and are the main persistence abstraction; no separate repository layer is present.

7. Protocol document/file handling

- app/Services/FileService.php is a dedicated service boundary for file operations.

- This likely supports protocol-related attachments, PDF handling, or uploads stored via Laravel’s filesystem abstraction (config/filesystems.php).

- The migration change_pdf_type_in_protocols implies protocol records store PDF-related data or references.

8. Email and communication flow

- Mail classes in app/Mail show a distinct outbound communication subsystem:

- BienvenidoVerifMail

- EnvioCorreoMailabre

- MensajeDeContacto

- RecuperarContrasena

- Corresponding Blade templates in resources/views support email content and likely public contact/recovery pages.

- This mail flow is important for account verification, password recovery, and contact messages.

9. Middleware and request processing

- The custom middleware UpdateTokenExpiry is notable because it suggests token lifecycle management beyond default Laravel behavior.

- Standard Laravel middleware handles CSRF, cookie encryption, proxy trust, host trust, maintenance mode, and auth gating.

- This indicates a conventional request pipeline with one custom extension around token freshness.

10. Presentation layer

- resources/views contains a small set of Blade templates (welcome, contacto, Recuperar, BienvenidoVerifMail, etc.), so the UI footprint is limited and mostly supportive.

- resources/js and resources/css exist with Vite configuration, but this appears secondary to the backend API role.

- The UI layer likely serves account/contact/recovery screens rather than a large SPA.

11. Operational and framework infrastructure

- The app uses standard Laravel providers, logging, cache, queue, broadcasting, and CORS configuration.

- config/queue.php and mail configuration imply asynchronous-capable infrastructure, even if the current codebase may primarily use synchronous execution.

- public/index.php is the web entry point, while artisan is the CLI/admin entry point.

12. Testing and documentation artifacts

- There is a basic PHPUnit setup under tests, currently with scaffold tests.

- umlDiagrams/ contains Visual Paradigm files, indicating the project has existing design documentation outside the codebase.

- These artifacts suggest the repository is maintained with explicit modeling/documentation in mind, even if implementation tests are minimal.

13. Overall data flow

- A typical request enters through Laravel routing, passes middleware/auth checks, reaches a controller, then reads/writes Eloquent models backed by PostgreSQL migrations.

- If needed, the controller delegates file work to FileService or email work to a Mailable class.

- Responses are returned as API payloads or Blade-rendered pages depending on the route group.

14. Architecture summary for a diagram

- The clearest diagram would show four layers: HTTP/API + Middleware, Controllers, Domain/Persistence Models, and Infrastructure services (database, mail, filesystem, auth tokens).

- The key external systems are PostgreSQL, email delivery, and Laravel Sanctum token auth.

- The app is not a generic frontend-heavy system; it is primarily a backend workflow service for managing protocol-related academic records and communications.