# alzuhairia/gestion_absences_universite architecture

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

- Interactive diagram: https://gitdiagram.com/alzuhairia/gestion_absences_universite
- Repository: https://github.com/alzuhairia/gestion_absences_universite

## Overview

1. UniAbsences is a Django monolith organized as a set of domain apps rather than a layered service architecture. The central runtime is Gunicorn running Django, with PostgreSQL as the system of record and Redis used for cache/rate-limiting style concerns.

2. The main business boundary is the attendance workflow. The `absences` app owns absence records, justification submission/review, QR attendance, GPS anti-fraud checks, and related utilities. It also contains custom management commands for maintenance jobs such as QR log cleanup and document migration, which indicates this domain has both interactive and batch-processing paths.

3. Academic structure is split across `academics` and `academic_sessions`. `academics` models faculties, departments, and courses; `academic_sessions` models academic years and teaching sessions. These apps provide the reference data that attendance, enrollment, dashboards, and rules depend on.

4. Identity and access are centralized in `accounts`. This app defines the custom user model, login/profile flows, 2FA setup and verification, backup codes, middleware for auth/session enforcement, and an admin superuser creation command. Role separation is a first-class architectural boundary: admin, secretary, professor, and student each have distinct views, templates, and permissions.

5. Student enrollment is isolated in `enrollments`. It manages registration status, exemption rules, and threshold-related eligibility logic. This app bridges academic structure and attendance policy, so it is one of the main data dependencies for both absence enforcement and dashboard reporting.

6. The `dashboard` app is the role-based presentation and control plane. It contains separate view modules for admin, secretary, professor, and student, plus export and statistics endpoints. This is where operational workflows converge: course management, settings, audits, user administration, attendance summaries, and data exports.

7. Communication and automation are split into `messaging` and `notifications`. `messaging` is the internal inbox/sent-box feature for authenticated users, while `notifications` handles outbound email delivery, templates, weekly summaries, and email logs. The email subsystem is closely tied to absence events, justification decisions, and threshold alerts.

8. Security and traceability are provided by `audits` and by the account middleware/2FA stack. `audits` persists sensitive action logs and exposes audit views, while `accounts` and `middleware_2fa.py` enforce stronger login/session controls. The repository’s tests and scripts suggest auditability is treated as a core requirement rather than an add-on.

9. The REST API lives under `apps/api` and wraps the same domain data through serializers, permissions, filters, throttles, and pagination. This is not a separate backend; it is an alternate interface over the same Django models and business rules used by the server-rendered pages.

10. The UI is server-rendered Django templates, organized by domain and role. Base templates such as `base_admin.html`, `base_secretary.html`, `base_instructor.html`, and `base_student.html` show that presentation is segmented by permission group. HTMX is used for some real-time interactions, especially attendance marking, without turning the project into a separate SPA.

11. Background and operational workflows are handled with Django management commands and helper scripts. Examples include seeding demo/UAT data, generating weekly summaries, fixing schema/data issues, and maintenance/verification scripts. This indicates the repository is built for institutional deployment with ongoing admin operations, not just request/response traffic.

12. Infrastructure is containerized. Docker Compose orchestrates at least the web app, PostgreSQL, Redis, Nginx, and monitoring. Nginx terminates TLS, serves static/media content, and reverse-proxies to Django. Redis supports application-side performance and throttling concerns. Uptime Kuma and a health endpoint provide availability monitoring.

13. The request flow is therefore: browser or API client -> Nginx -> Django/Gunicorn -> domain app logic -> PostgreSQL, with Redis used where request shaping or caching is needed, and email/notifications emitted asynchronously from business events. Most cross-cutting behavior is implemented inside Django apps via services, signals, middleware, and role-specific views rather than via external microservices.

14. The repository’s tests mirror these boundaries: there are dedicated tests for 2FA, absences, QR/GPS, sessions, enrollments, messaging, middleware, health, API auth, and performance queries. That test layout reflects the architecture: a modular monolith with strong domain separation, shared persistence, and role-aware workflows.

Main entry points: [`config/urls.py`](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/config/urls.py) (URL router), [`apps/absences/models.py`](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/absences/models.py) (Absences), [`apps/dashboard/views.py`](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/dashboard/views.py) (Dashboard), [`apps/api/views.py`](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/api/views.py) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Platform"]
  node_gunicorn_django["Django app<br/>runtime<br/>[wsgi.py]"]
  node_settings["Settings<br/>config<br/>[settings.py]"]
  node_routing["URL router<br/>routing<br/>[urls.py]"]
  node_compose["Compose stack<br/>deployment<br/>[docker-compose.yml]"]
  node_nginx["Reverse proxy<br/>edge-proxy<br/>[nginx.conf]"]
  node_redis[("Redis cache<br/>[redis.conf]")]
end

subgraph group_identity["Identity"]
  node_accounts["Accounts<br/>auth app<br/>[models.py]"]
  node_accounts_2fa["2FA stack<br/>auth control<br/>[middleware_2fa.py]"]
end

subgraph group_academic["Academic data"]
  node_academics["Academics<br/>reference app<br/>[models.py]"]
  node_sessions["Sessions<br/>reference app<br/>[models.py]"]
end

subgraph group_attendance["Attendance"]
  node_enrollments["Enrollments<br/>policy app<br/>[models.py]"]
  node_absences["Absences<br/>workflow app<br/>[models.py]"]
  node_audits["Audits<br/>audit app<br/>[models.py]"]
end

subgraph group_presentation["Presentation"]
  node_dashboard["Dashboard<br/>control plane<br/>[views.py]"]
  node_api["REST API<br/>api layer<br/>[views.py]"]
  node_templates["Templates<br/>server UI<br/>[base.html]"]
end

subgraph group_communication["Communication"]
  node_messaging["Messaging<br/>inbox app<br/>[models.py]"]
  node_notifications["Notifications<br/>email app<br/>[email.py]"]
end

subgraph group_ops["Ops"]
  node_health(("Health<br/>monitoring<br/>[views.py]"))
  node_scripts["Scripts<br/>maintenance<br/>[check_schema.py]"]
end

node_compose -->|"routes through"| node_nginx
node_compose -->|"runs"| node_gunicorn_django
node_compose -->|"provides cache"| node_redis
node_nginx -->|"proxies"| node_gunicorn_django
node_gunicorn_django -->|"loads"| node_settings
node_gunicorn_django -->|"dispatches"| node_routing
node_routing -->|"includes"| node_accounts
node_routing -->|"includes"| node_academics
node_routing -->|"includes"| node_sessions
node_routing -->|"includes"| node_enrollments
node_routing -->|"includes"| node_absences
node_routing -->|"includes"| node_dashboard
node_routing -->|"includes"| node_api
node_routing -->|"includes"| node_messaging
node_routing -->|"includes"| node_notifications
node_routing -->|"includes"| node_audits
node_routing -->|"includes"| node_health
node_accounts_2fa -->|"extends"| node_accounts
node_academics -->|"depends on"| node_sessions
node_enrollments -->|"depends on"| node_academics
node_enrollments -->|"depends on"| node_sessions
node_absences -->|"depends on"| node_academics
node_absences -->|"depends on"| node_sessions
node_absences -->|"depends on"| node_enrollments
node_absences -->|"emits logs"| node_audits
node_dashboard -->|"uses roles"| node_accounts
node_dashboard -->|"manages"| node_academics
node_dashboard -->|"manages"| node_sessions
node_dashboard -->|"manages"| node_enrollments
node_dashboard -->|"reviews"| node_absences
node_dashboard -->|"reviews"| node_audits
node_api -->|"secures"| node_accounts
node_api -->|"serializes"| node_academics
node_api -->|"serializes"| node_sessions
node_api -->|"serializes"| node_enrollments
node_api -->|"serializes"| node_absences
node_api -->|"supports"| node_dashboard
node_templates -->|"renders"| node_dashboard
node_templates -->|"renders"| node_accounts
node_templates -->|"renders"| node_absences
node_messaging -->|"authenticates"| node_accounts
node_notifications -->|"notifies"| node_absences
node_notifications -->|"notifies"| node_enrollments
node_notifications -->|"notifies"| node_accounts
node_audits -->|"records"| node_accounts
node_scripts -->|"maintains"| node_gunicorn_django
node_scripts -->|"maintains"| node_absences
node_scripts -->|"maintains"| node_notifications

click node_gunicorn_django "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/config/wsgi.py"
click node_settings "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/config/settings.py"
click node_routing "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/config/urls.py"
click node_compose "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/docker-compose.yml"
click node_nginx "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/nginx/nginx.conf"
click node_redis "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/redis/redis.conf"
click node_accounts "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/accounts/models.py"
click node_accounts_2fa "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/accounts/middleware_2fa.py"
click node_academics "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/academics/models.py"
click node_sessions "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/academic_sessions/models.py"
click node_enrollments "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/enrollments/models.py"
click node_absences "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/absences/models.py"
click node_audits "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/audits/models.py"
click node_dashboard "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/dashboard/views.py"
click node_api "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/api/views.py"
click node_templates "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/templates/base.html"
click node_messaging "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/messaging/models.py"
click node_notifications "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/notifications/email.py"
click node_health "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/health/views.py"
click node_scripts "https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/scripts/maintenance/check_schema.py"

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_gunicorn_django,node_settings,node_routing,node_compose,node_nginx,node_redis,node_health,node_scripts toneBlue
class node_accounts,node_accounts_2fa toneAmber
class node_academics,node_sessions toneMint
class node_enrollments,node_absences,node_audits toneRose
class node_dashboard,node_api,node_templates toneIndigo
class node_messaging,node_notifications toneTeal
```

## Components

### Platform

Django runtime, deployment, cache, and operational tooling.

- [Django app](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/config/wsgi.py): runtime · Main Django application runtime served by Gunicorn. · `config/wsgi.py`
- [Settings](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/config/settings.py): config · Central Django configuration and environment wiring. · `config/settings.py`
- [URL router](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/config/urls.py): routing · Top-level URL dispatch into domain apps and API. · `config/urls.py`
- [Compose stack](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/docker-compose.yml): deployment · Container orchestration for web, database, cache, and proxy. · `docker-compose.yml`
- [Reverse proxy](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/nginx/nginx.conf): edge-proxy · TLS termination, static/media serving, and proxying to Django. · `nginx/nginx.conf`
- [Redis cache](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/redis/redis.conf): cache · Cache and request-shaping support such as throttling. · `redis/redis.conf`

### Identity

Authentication, roles, and session enforcement.

- [Accounts](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/accounts/models.py): auth app · Custom user model, login/profile flows, 2FA, and session controls. · `apps/accounts/models.py`
- [2FA stack](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/accounts/middleware_2fa.py): auth control · Two-factor setup, verification, backup codes, and session enforcement middleware. · `apps/accounts/middleware_2fa.py`

### Academic data

Reference data for institutions, years, and teaching sessions.

- [Academics](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/academics/models.py): reference app · Faculties, departments, and courses. · `apps/academics/models.py`
- [Sessions](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/academic_sessions/models.py): reference app · Academic years and teaching sessions. · `apps/academic_sessions/models.py`

### Attendance

Absence workflow, enrollment rules, and audit trail.

- [Enrollments](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/enrollments/models.py): policy app · Registration status, exemptions, and eligibility thresholds. · `apps/enrollments/models.py`
- [Absences](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/absences/models.py): workflow app · Absence records, justifications, QR attendance, and GPS anti-fraud checks. · `apps/absences/models.py`
- [Audits](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/audits/models.py): audit app · Sensitive action logging and audit views. · `apps/audits/models.py`

### Presentation

Server-rendered role-based UI and API surface.

- [Dashboard](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/dashboard/views.py): control plane · Role-based admin, secretary, professor, and student workflows. · `apps/dashboard/views.py`
- [REST API](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/api/views.py): api layer · Serializers, permissions, filters, throttles, and pagination over the same domain models. · `apps/api/views.py`
- [Templates](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/templates/base.html): server UI · Role-segmented Django templates and shared bases. · `templates/base.html`

### Communication

Messaging and email notifications.

- [Messaging](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/messaging/models.py): inbox app · Internal inbox and sent-box for authenticated users. · `apps/messaging/models.py`
- [Notifications](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/notifications/email.py): email app · Outbound email delivery, templates, logs, and weekly summaries. · `apps/notifications/email.py`

### Ops

Health, scripts, and maintenance workflows.

- [Health](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/apps/health/views.py): monitoring · Availability and readiness endpoints. · `apps/health/views.py`
- [Scripts](https://github.com/alzuhairia/gestion_absences_universite/blob/Dev/scripts/maintenance/check_schema.py): maintenance · Setup, verification, repair, and maintenance commands. · `scripts/maintenance/check_schema.py`

## Connections

- Compose stack → Reverse proxy: routes through · Nginx fronts the web application stack.
- Compose stack → Django app: runs · Compose starts the Django web runtime.
- Compose stack → Redis cache: provides cache · Redis is part of the deployment stack.
- Reverse proxy → Django app: proxies · Requests are reverse-proxied to Django/Gunicorn.
- Django app → Settings: loads · Runtime behavior is driven by Django settings.
- Django app → URL router: dispatches · Top-level URL routing enters the app boundary.
- URL router → Accounts: includes · Authentication and profile flows are mounted here.
- URL router → Academics: includes · Academic reference data routes are mounted here.
- URL router → Sessions: includes · Academic session routes are mounted here.
- URL router → Enrollments: includes · Enrollment and rule routes are mounted here.
- URL router → Absences: includes · Attendance workflow routes are mounted here.
- URL router → Dashboard: includes · Role-based dashboard routes are mounted here.
- URL router → REST API: includes · REST API routes are mounted here.
- URL router → Messaging: includes · Internal messaging routes are mounted here.
- URL router → Notifications: includes · Notification-related routes are mounted here.
- URL router → Audits: includes · Audit views are exposed through routing.
- URL router → Health: includes · Health endpoint routes are mounted here.
- 2FA stack → Accounts: extends · 2FA and middleware deepen the account boundary.
- Academics → Sessions: depends on · Courses and structure are tied to academic sessions.
- Enrollments → Academics: depends on · Enrollment policy references academic structure.
- Enrollments → Sessions: depends on · Eligibility and status are session-aware.
- Absences → Academics: depends on · Attendance is evaluated against courses and departments.
- Absences → Sessions: depends on · Absence records are bound to teaching sessions.
- Absences → Enrollments: depends on · Policy checks use enrollment and exemption rules.
- Absences → Audits: emits logs · Sensitive attendance actions are audit-worthy.
- Dashboard → Accounts: uses roles · Role-specific views and permissions are account-driven.
- Dashboard → Academics: manages · Admins and secretaries manage academic structure.
- Dashboard → Sessions: manages · Session administration flows live in the dashboard.
- Dashboard → Enrollments: manages · Enrollment oversight and thresholds are surfaced here.
- Dashboard → Absences: reviews · Absence summaries, validation, and QR operations converge here.
- Dashboard → Audits: reviews · Audit logs are presented in the control plane.
- REST API → Accounts: secures · API permissions and auth are account-based.
- REST API → Academics: serializes · Academic reference data is exposed through the API.
- REST API → Sessions: serializes · Academic session data is exposed through the API.
- REST API → Enrollments: serializes · Enrollment and rule data are exposed through the API.
- REST API → Absences: serializes · Attendance and justification data are exposed through the API.
- REST API → Dashboard: supports · The API is an alternate interface over the same domain rules.
- Templates → Dashboard: renders · Role-specific pages are primarily dashboard-driven.
- Templates → Accounts: renders · Login, profile, and 2FA flows use dedicated templates.
- Templates → Absences: renders · Attendance and QR workflows are server-rendered.
- Messaging → Accounts: authenticates · Only authenticated roles can use the inbox.
- Notifications → Absences: notifies · Absence events trigger email notifications.
- Notifications → Enrollments: notifies · Eligibility and threshold changes can emit email alerts.
- Notifications → Accounts: notifies · Account-related messages and summaries depend on users.
- Audits → Accounts: records · Audit records are tied to user identity.
- Scripts → Django app: maintains · Maintenance and verification scripts support the deployed app.
- Scripts → Absences: maintains · Domain scripts cover attendance maintenance jobs.
- Scripts → Notifications: maintains · Operational scripts support email and summary workflows.
