# koventhanventhan/tit architecture

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

- Interactive diagram: https://gitdiagram.com/koventhanventhan/tit
- Repository: https://github.com/koventhanventhan/tit

## Overview

#### 1. Purpose and deployable shape
This is a multi-tenant education-management SaaS: public marketing/registration plus role-specific student, teacher/admin, and super-admin portals. It combines a React/Vite SPA with a Laravel API/admin backend.
- Frontend bootstrap: `src/main.jsx`, `src/App.jsx`
- Laravel HTTP bootstrap and route surfaces: `backend/public/index.php`, `backend/routes/api.php`, `backend/routes/web.php`
- Container/deployment artifacts: `Dockerfile.frontend`, `backend/Dockerfile`, `railway.json`

#### 2. Frontend application shell and role portals
The React app owns client routing, public pages, authentication presentation, settings/language context, and dashboard layouts. It separates role experiences rather than being only a marketing site.
- App shell/context: `src/App.jsx`, `src/context/AuthModalContext.jsx`, `src/context/SettingsContext.jsx`
- Student UI: `src/components/student/StudentDashboardLayout.jsx`, `src/pages/student/StudentOverview.jsx`
- Teacher/admin and platform UI: `src/components/teacher/TeacherDashboardLayout.jsx`, `src/pages/admin/AdminOverview.jsx`, `src/pages/super-admin/SuperAdminOverview.jsx`

#### 3. API boundary, identity, and tenancy
Laravel controllers expose the application boundary for SPA clients. Authentication and access are constrained by role, registration state/session timeout, and institute tenancy; tenant scoping is also modeled at ORM level.
- Auth/registration endpoints: `backend/app/Http/Controllers/AuthController.php`, `backend/app/Http/Controllers/RegistrationController.php`
- Authorization/tenant boundary: `backend/app/Http/Middleware/RoleMiddleware.php`, `backend/app/Http/Middleware/TenantMiddleware.php`, `backend/app/Scopes/InstituteScope.php`
- Principal model and tenant association trait: `backend/app/Models/User.php`, `backend/app/Models/Institute.php`, `backend/app/Traits/BelongsToInstitute.php`

#### 4. Core academic operations
The primary application flow is institute users managing students, teachers, subjects, teaching materials, assignments/submissions, attendance, timetables, Zoom sessions, and exam results. Role-specific API controllers feed corresponding React dashboards.
- Academic records: `backend/app/Models/Assignment.php`, `backend/app/Models/AssignmentSubmission.php`, `backend/app/Models/LearningMaterial.php`
- Scheduling/class delivery: `backend/app/Models/Timetable.php`, `backend/app/Models/ZoomSchedule.php`, `backend/app/Models/Attendance.php`
- Role APIs: `backend/app/Http/Controllers/Api/StudentDashboardController.php`, `backend/app/Http/Controllers/Api/TeacherDashboardController.php`, `backend/app/Http/Controllers/Api/ExamResultController.php`

#### 5. SaaS administration, subscriptions, and payments
Super-admin functionality manages institutes, subscription plans, coupons, payments, activity visibility, announcements, and platform settings. Institute lifecycle and payment state likely gate tenant access through the shared identity/registration layer.
- Commercial domain: `backend/app/Models/SubscriptionPlan.php`, `backend/app/Models/Payment.php`, `backend/app/Models/Coupon.php`
- Service layer: `backend/app/Services/SubscriptionService.php`, `backend/app/Services/PayHereService.php`
- Filament platform back office: `backend/app/Providers/Filament/SuperAdminPanelProvider.php`, `backend/app/Filament/SuperAdmin/Resources/InstituteResource.php`, `backend/app/Filament/SuperAdmin/Resources/PaymentResource.php`

#### 6. Communication and external integrations
The backend integrates payment processing, Zoom scheduling/synchronization, WhatsApp, Gemini translation, email notifications, and Laravel broadcasting. These sit behind services and are invoked through controllers, events, or scheduled commands.
- Integration services: `backend/app/Services/ZoomService.php`, `backend/app/Services/WhatsAppService.php`, `backend/app/Services/GeminiTranslationService.php`
- Notifications/realtime: `backend/app/Events/NewMessageEvent.php`, `backend/app/Services/NotificationService.php`, `src/services/echo.js`
- Recurring integration work: `backend/app/Console/Commands/CheckPayments.php`, `backend/app/Console/Commands/SyncTimetableToZoom.php`, `backend/app/Console/Commands/SendZoomReminders.php`

#### 7. Persistence and operational boundaries
Laravel migrations define a relational persistence model spanning users, tenant ownership, academic entities, payments, notifications, and queued jobs. Uploaded learning assets are served from backend public storage paths. PHP/Laravel runs behind Nginx in Docker; the SPA is independently built and served.
- Schema evolution: `backend/database/migrations/2026_02_07_053609_create_institutes_and_plans_tables.php`, `backend/database/migrations/2026_02_07_053611_add_institute_id_to_existing_tables.php`
- Files/assets: `backend/public/uploads`, `backend/config/filesystems.php`
- Runtime web-server wiring: `backend/docker/nginx.conf`, `nginx.frontend.conf.template`, `frontend_entrypoint.sh`

The `teste_herd/` and `tit_website/` trees appear to be standalone minimal Laravel scaffolds, not part of the primary product runtime.

Main entry points: [`backend/routes/api.php`](https://github.com/koventhanventhan/tit/blob/main/backend/routes/api.php) (API route surface), [`backend/app/Models/Assignment.php`](https://github.com/koventhanventhan/tit/blob/main/backend/app/Models/Assignment.php) (Academic operations), [`backend/app/Services/SubscriptionService.php`](https://github.com/koventhanventhan/tit/blob/main/backend/app/Services/SubscriptionService.php) (Subscriptions & payments), [`src/App.jsx`](https://github.com/koventhanventhan/tit/blob/main/src/App.jsx) (App shell & contexts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_spa_bootstrap["SPA bootstrap<br/>React/Vite entry<br/>[main.jsx]"]
  node_app_shell["App shell &amp; contexts<br/>React routing<br/>[App.jsx]"]
  node_student_portal["Student portal<br/>React dashboard"]
  node_staff_portals["Teacher, admin &amp; super-admin portals<br/>React dashboards"]
  node_frontend_runtime["SPA runtime<br/>Frontend container"]
end

subgraph group_backend["Laravel application"]
  node_api_routes["API route surface<br/>Laravel routes<br/>[api.php]"]
  node_auth_registration["Auth &amp; registration<br/>Laravel controllers<br/>[AuthController.php]"]
  node_access_tenancy{{"Role &amp; tenant enforcement<br/>Laravel middleware<br/>[RoleMiddleware.php]"}}
  node_tenant_domain["Users &amp; institutes<br/>Eloquent models<br/>[User.php]"]
  node_academic_apis["Academic role APIs<br/>Laravel controllers"]
  node_academic_domain["Academic operations<br/>Eloquent models<br/>[Assignment.php]"]
  node_saas_services["Subscriptions &amp; payments<br/>Laravel services"]
  node_filament_backoffice["Platform back office<br/>Filament panel"]
  node_database[("Relational database<br/>Laravel migrations")]
  node_uploads["Learning asset storage<br/>Public uploads"]
  node_backend_runtime["Laravel web runtime<br/>PHP-FPM + Nginx<br/>[nginx.conf]"]
end

subgraph group_integrations["Integrations &amp; operations"]
  node_notifications_realtime["Notifications &amp; realtime<br/>Events and services"]
  node_external_services["External service adapters<br/>Laravel services<br/>[ZoomService.php]"]
  node_scheduled_jobs["Scheduled integration jobs<br/>Laravel commands"]
end

node_spa_bootstrap -->|"mounts"| node_app_shell
node_app_shell -->|"routes to"| node_student_portal
node_app_shell -->|"routes to"| node_staff_portals
node_student_portal -->|"uses"| node_api_routes
node_staff_portals -->|"uses"| node_api_routes
node_api_routes -->|"auth endpoints"| node_auth_registration
node_api_routes -->|"guarded by"| node_access_tenancy
node_access_tenancy -->|"resolves tenant"| node_tenant_domain
node_api_routes -->|"dispatches"| node_academic_apis
node_academic_apis -->|"manages"| node_academic_domain
node_academic_domain -->|"persists"| node_database
node_academic_domain -->|"stores learning assets"| node_uploads
node_auth_registration -.->|"applies access lifecycle"| node_saas_services
node_saas_services -->|"records plans and payments"| node_database
node_filament_backoffice -->|"manages institutes"| node_tenant_domain
node_filament_backoffice -->|"administers"| node_saas_services
node_academic_domain -->|"schedules Zoom"| node_external_services
node_scheduled_jobs -->|"runs syncs and reminders"| node_external_services
node_scheduled_jobs -->|"checks payments"| node_saas_services
node_academic_apis -.->|"emits updates"| node_notifications_realtime
node_frontend_runtime -->|"builds and serves"| node_spa_bootstrap
node_backend_runtime -->|"serves"| node_api_routes

click node_spa_bootstrap "https://github.com/koventhanventhan/tit/blob/main/src/main.jsx"
click node_app_shell "https://github.com/koventhanventhan/tit/blob/main/src/App.jsx"
click node_student_portal "https://github.com/koventhanventhan/tit/blob/main/src/components/student/StudentDashboardLayout.jsx"
click node_staff_portals "https://github.com/koventhanventhan/tit/blob/main/src/components/teacher/TeacherDashboardLayout.jsx"
click node_api_routes "https://github.com/koventhanventhan/tit/blob/main/backend/routes/api.php"
click node_auth_registration "https://github.com/koventhanventhan/tit/blob/main/backend/app/Http/Controllers/AuthController.php"
click node_access_tenancy "https://github.com/koventhanventhan/tit/blob/main/backend/app/Http/Middleware/RoleMiddleware.php"
click node_tenant_domain "https://github.com/koventhanventhan/tit/blob/main/backend/app/Models/User.php"
click node_academic_apis "https://github.com/koventhanventhan/tit/blob/main/backend/app/Http/Controllers/Api/StudentDashboardController.php"
click node_academic_domain "https://github.com/koventhanventhan/tit/blob/main/backend/app/Models/Assignment.php"
click node_saas_services "https://github.com/koventhanventhan/tit/blob/main/backend/app/Services/SubscriptionService.php"
click node_filament_backoffice "https://github.com/koventhanventhan/tit/blob/main/backend/app/Providers/Filament/SuperAdminPanelProvider.php"
click node_database "https://github.com/koventhanventhan/tit/blob/main/backend/database/migrations/2026_02_07_053609_create_institutes_and_plans_tables.php"
click node_uploads "https://github.com/koventhanventhan/tit/tree/main/backend/public/uploads"
click node_notifications_realtime "https://github.com/koventhanventhan/tit/blob/main/backend/app/Events/NewMessageEvent.php"
click node_external_services "https://github.com/koventhanventhan/tit/blob/main/backend/app/Services/ZoomService.php"
click node_scheduled_jobs "https://github.com/koventhanventhan/tit/blob/main/backend/app/Console/Commands/SyncTimetableToZoom.php"
click node_backend_runtime "https://github.com/koventhanventhan/tit/blob/main/backend/docker/nginx.conf"
click node_frontend_runtime "https://github.com/koventhanventhan/tit/blob/main/Dockerfile.frontend"

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_spa_bootstrap,node_app_shell,node_student_portal,node_staff_portals,node_frontend_runtime toneBlue
class node_api_routes,node_auth_registration,node_access_tenancy,node_tenant_domain,node_academic_apis,node_academic_domain,node_saas_services,node_filament_backoffice,node_database,node_uploads,node_backend_runtime toneAmber
class node_notifications_realtime,node_external_services,node_scheduled_jobs toneMint
```

## Components

### React SPA

Public registration and role-specific portals.

- [SPA bootstrap](https://github.com/koventhanventhan/tit/blob/main/src/main.jsx): React/Vite entry · `src/main.jsx`
- [App shell & contexts](https://github.com/koventhanventhan/tit/blob/main/src/App.jsx): React routing · Owns routing, auth presentation, settings, and language state. · `src/App.jsx`
- [Student portal](https://github.com/koventhanventhan/tit/blob/main/src/components/student/StudentDashboardLayout.jsx): React dashboard · `src/components/student/StudentDashboardLayout.jsx`
- [Teacher, admin & super-admin portals](https://github.com/koventhanventhan/tit/blob/main/src/components/teacher/TeacherDashboardLayout.jsx): React dashboards · `src/components/teacher/TeacherDashboardLayout.jsx`
- [SPA runtime](https://github.com/koventhanventhan/tit/blob/main/Dockerfile.frontend): Frontend container · Independently builds and serves the React application. · `Dockerfile.frontend`

### Laravel application

API, tenancy, academic operations, and SaaS administration.

- [API route surface](https://github.com/koventhanventhan/tit/blob/main/backend/routes/api.php): Laravel routes · SPA-facing application endpoint boundary. · `backend/routes/api.php`
- [Auth & registration](https://github.com/koventhanventhan/tit/blob/main/backend/app/Http/Controllers/AuthController.php): Laravel controllers · `backend/app/Http/Controllers/AuthController.php`
- [Role & tenant enforcement](https://github.com/koventhanventhan/tit/blob/main/backend/app/Http/Middleware/RoleMiddleware.php): Laravel middleware · Constrains requests by role, registration state, and institute. · `backend/app/Http/Middleware/RoleMiddleware.php`
- [Users & institutes](https://github.com/koventhanventhan/tit/blob/main/backend/app/Models/User.php): Eloquent models · Institute association is the tenancy root. · `backend/app/Models/User.php`
- [Academic role APIs](https://github.com/koventhanventhan/tit/blob/main/backend/app/Http/Controllers/Api/StudentDashboardController.php): Laravel controllers · Serves student, teacher, and exam-result dashboard data. · `backend/app/Http/Controllers/Api/StudentDashboardController.php`
- [Academic operations](https://github.com/koventhanventhan/tit/blob/main/backend/app/Models/Assignment.php): Eloquent models · Assignments, materials, attendance, timetables, Zoom schedules, and results. · `backend/app/Models/Assignment.php`
- [Subscriptions & payments](https://github.com/koventhanventhan/tit/blob/main/backend/app/Services/SubscriptionService.php): Laravel services · Manages plan lifecycle and PayHere payment processing. · `backend/app/Services/SubscriptionService.php`
- [Platform back office](https://github.com/koventhanventhan/tit/blob/main/backend/app/Providers/Filament/SuperAdminPanelProvider.php): Filament panel · Super-admin manages institutes and payments. · `backend/app/Providers/Filament/SuperAdminPanelProvider.php`
- [Relational database](https://github.com/koventhanventhan/tit/blob/main/backend/database/migrations/2026_02_07_053609_create_institutes_and_plans_tables.php): Laravel migrations · Stores tenants, academic records, payments, notifications, and jobs. · `backend/database/migrations/2026_02_07_053609_create_institutes_and_plans_tables.php`
- [Learning asset storage](https://github.com/koventhanventhan/tit/tree/main/backend/public/uploads): Public uploads · `backend/public/uploads`
- [Laravel web runtime](https://github.com/koventhanventhan/tit/blob/main/backend/docker/nginx.conf): PHP-FPM + Nginx · Serves Laravel behind Nginx in Docker. · `backend/docker/nginx.conf`

### Integrations & operations

External services and recurring backend work.

- [Notifications & realtime](https://github.com/koventhanventhan/tit/blob/main/backend/app/Events/NewMessageEvent.php): Events and services · Broadcasts new messages and delivers notifications. · `backend/app/Events/NewMessageEvent.php`
- [External service adapters](https://github.com/koventhanventhan/tit/blob/main/backend/app/Services/ZoomService.php): Laravel services · Zoom, WhatsApp, Gemini translation, and PayHere integrations. · `backend/app/Services/ZoomService.php`
- [Scheduled integration jobs](https://github.com/koventhanventhan/tit/blob/main/backend/app/Console/Commands/SyncTimetableToZoom.php): Laravel commands · Checks payments, syncs timetables to Zoom, and sends reminders. · `backend/app/Console/Commands/SyncTimetableToZoom.php`

## Connections

- SPA bootstrap → App shell & contexts: mounts
- App shell & contexts → Student portal: routes to
- App shell & contexts → Teacher, admin & super-admin portals: routes to
- Student portal → API route surface: uses
- Teacher, admin & super-admin portals → API route surface: uses
- API route surface → Auth & registration: auth endpoints
- API route surface → Role & tenant enforcement: guarded by
- Role & tenant enforcement → Users & institutes: resolves tenant
- API route surface → Academic role APIs: dispatches
- Academic role APIs → Academic operations: manages
- Academic operations → Relational database: persists
- Academic operations → Learning asset storage: stores learning assets
- Auth & registration → Subscriptions & payments: applies access lifecycle
- Subscriptions & payments → Relational database: records plans and payments
- Platform back office → Users & institutes: manages institutes
- Platform back office → Subscriptions & payments: administers
- Academic operations → External service adapters: schedules Zoom
- Scheduled integration jobs → External service adapters: runs syncs and reminders
- Scheduled integration jobs → Subscriptions & payments: checks payments
- Academic role APIs → Notifications & realtime: emits updates
- SPA runtime → SPA bootstrap: builds and serves
- Laravel web runtime → API route surface: serves