# riadhlaroui/diploma_archive architecture

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

- Interactive diagram: https://gitdiagram.com/riadhlaroui/diploma_archive
- Repository: https://github.com/riadhlaroui/diploma_archive

## Overview

#### Purpose and Runtime
This is a Next.js diploma archive administration system. It manages students, academic taxonomy (faculties through specialties), staff, document types, diploma-document workflows, and printing. The application is containerized with Docker and deployed behind Nginx; PocketBase is the embedded backend/database service.

Paths: `Dockerfile`, `docker-compose.yml`, `nginx/nginx.conf`, `pocketbase/Dockerfile`

#### Application Entry and Route Partitioning
The App Router starts at `app/layout.tsx` and `app/page.tsx`. Routes are partitioned into authentication and protected/main application shells, each with a distinct layout. Main navigation leads to dashboard, student records, organization hierarchy, team, inbox, profile, and settings.

Paths: `app/(auth)/layout.tsx`, `app/(main)/layout.tsx`, `app/(main)/dashboard/page.tsx`

#### Authentication and Session Boundary
Client authentication is backed by PocketBase. Login and token refresh are exposed as Next API routes, while client services/hooks manage sign-in forms, session protection, and permission checks. Core entities and an authentication use case provide a lightweight domain boundary around the backend client.

Paths: `app/api/auth/login/route.ts`, `app/api/auth/refresh/route.ts`, `app/src/infrastructure/auth/pocketbaseClient.ts`, `app/src/core/use-cases/ensureUserIsAuthenticated.ts`, `middleware.ts`

#### Authorization Model
Permissions are centrally declared as permissions and groups, then consumed by client hooks to gate UI/actions. User identity is modeled separately from student identity, supporting staff/team administration alongside archive operations.

Paths: `app/src/config/permissions.ts`, `app/src/config/permissionGroups.ts`, `app/src/hooks/usePermission.ts`, `app/src/core/domain/entities/User.ts`

#### Archive and Academic Data Management
The main CRUD flow centers on student records, including individual creation/update, bulk entry/import, document upload/viewing, and diploma printing. Academic reference data is modeled as a navigable hierarchy: faculty → department → field → major → specialty. Service modules form the data-access boundary to PocketBase for each resource.

Paths: `app/(main)/students/page.tsx`, `app/(main)/students/bulk-import/page.tsx`, `components/StudentForm.jsx`, `app/src/services/studentService.ts`, `app/src/services/facultieService.ts`, `app/src/services/specialtyService.ts`

#### Document Extraction Pipeline
Uploaded diploma/archive documents can be handled through OCR UI components and two server-side API routes. One route is generic OCR and one explicitly integrates Gemini, keeping external AI/OCR invocation on the server boundary rather than in browser-facing components.

Paths: `components/OCRUploader.tsx`, `components/DocumentUploadDialog.tsx`, `app/api/ocr/route.ts`, `app/api/ocr-gemini/route.ts`, `app/src/shared/utils/ocr.ts`

#### Data, External Services, and Delivery
PocketBase provides authentication, collections, and persisted data; its bundled `pb_data` indicates local SQLite-backed state. Google Gemini is an external OCR/AI integration. Internationalization supports Arabic, English, and French. Nginx fronts the Next.js application in the composed deployment.

Paths: `pocketbase/pocketbase_0.34.2_linux_amd64/pb_data/data.db`, `lib/pocketbase.js`, `lib/i18n/i18n.ts`, `lib/i18n/locales/ar/translation.json`, `nginx/nginx.conf`

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Next.js UI"]
  node_app_shell["App Router shell<br/>Next.js entry<br/>[layout.tsx]"]
  node_auth_shell["Authentication shell<br/>route layout<br/>[layout.tsx]"]
  node_main_shell["Protected app shell<br/>route layout<br/>[layout.tsx]"]
  node_dashboard["Dashboard<br/>main route<br/>[page.tsx]"]
  node_student_records["Student records<br/>archive routes<br/>[page.tsx]"]
  node_bulk_import["Bulk student import<br/>main route<br/>[page.tsx]"]
  node_student_form["Student form<br/>UI component<br/>[StudentForm.jsx]"]
  node_document_upload["Document upload &amp; OCR UI<br/>UI components<br/>[OCRUploader.tsx]"]
  node_i18n["Arabic, English &amp; French i18n<br/>localization<br/>[i18n.ts]"]
end

subgraph group_application["Application Services"]
  node_auth_api{{"Login &amp; token refresh<br/>Next API routes<br/>[route.ts]"}}
  node_auth_guard["Session guard<br/>auth use case"]
  node_route_middleware["Route middleware<br/>request guard<br/>[middleware.ts]"]
  node_authorization["Permission checks<br/>authorization hook<br/>[usePermission.ts]"]
  node_student_service["Student data service<br/>PocketBase service<br/>[studentService.ts]"]
  node_academic_services["Academic taxonomy services<br/>PocketBase services<br/>[facultieService.ts]"]
  node_ocr_api{{"OCR API<br/>Next API route<br/>[route.ts]"}}
  node_gemini_ocr_api{{"Gemini OCR API<br/>Next API route<br/>[route.ts]"}}
end

subgraph group_backend["Backend &amp; Integrations"]
  node_pocketbase[("PocketBase<br/>auth and collections backend")]
  node_archive_database[("PocketBase SQLite data<br/>persisted state<br/>[data.db]")]
  node_gemini{{"Google Gemini<br/>external AI/OCR"}}
end

subgraph group_delivery["Deployment"]
  node_nginx["Nginx reverse proxy<br/>edge proxy<br/>[nginx.conf]"]
  node_container_stack["Docker Compose stack<br/>deployment composition<br/>[docker-compose.yml]"]
end

node_app_shell -->|"partitions routes"| node_auth_shell
node_app_shell -->|"partitions routes"| node_main_shell
node_main_shell -->|"hosts"| node_dashboard
node_main_shell -->|"hosts"| node_student_records
node_student_records -->|"supports"| node_bulk_import
node_student_records -->|"uses"| node_student_form
node_student_records -->|"uploads documents"| node_document_upload
node_main_shell -->|"gates UI/actions"| node_authorization
node_route_middleware -->|"enforces session"| node_auth_guard
node_auth_guard -->|"validates session"| node_pocketbase
node_auth_api -->|"sign-in and refresh"| node_pocketbase
node_student_form -->|"creates and updates"| node_student_service
node_student_records -->|"reads archive records"| node_student_service
node_student_records -->|"selects taxonomy"| node_academic_services
node_student_service -->|"collection access"| node_pocketbase
node_academic_services -->|"collection access"| node_pocketbase
node_document_upload -->|"submits OCR"| node_ocr_api
node_document_upload -->|"submits AI OCR"| node_gemini_ocr_api
node_gemini_ocr_api -->|"invokes"| node_gemini
node_pocketbase -->|"persists data"| node_archive_database
node_nginx -->|"proxies requests"| node_app_shell
node_container_stack -->|"runs"| node_nginx
node_container_stack -->|"runs"| node_pocketbase
node_app_shell -->|"localizes UI"| node_i18n

click node_app_shell "https://github.com/riadhlaroui/diploma_archive/blob/main/app/layout.tsx"
click node_auth_shell "https://github.com/riadhlaroui/diploma_archive/blob/main/app/(auth)/layout.tsx"
click node_main_shell "https://github.com/riadhlaroui/diploma_archive/blob/main/app/(main)/layout.tsx"
click node_dashboard "https://github.com/riadhlaroui/diploma_archive/blob/main/app/(main)/dashboard/page.tsx"
click node_student_records "https://github.com/riadhlaroui/diploma_archive/blob/main/app/(main)/students/page.tsx"
click node_bulk_import "https://github.com/riadhlaroui/diploma_archive/blob/main/app/(main)/students/bulk-import/page.tsx"
click node_student_form "https://github.com/riadhlaroui/diploma_archive/blob/main/components/StudentForm.jsx"
click node_document_upload "https://github.com/riadhlaroui/diploma_archive/blob/main/components/OCRUploader.tsx"
click node_auth_api "https://github.com/riadhlaroui/diploma_archive/blob/main/app/api/auth/login/route.ts"
click node_auth_guard "https://github.com/riadhlaroui/diploma_archive/blob/main/app/src/core/use-cases/ensureUserIsAuthenticated.ts"
click node_route_middleware "https://github.com/riadhlaroui/diploma_archive/blob/main/middleware.ts"
click node_authorization "https://github.com/riadhlaroui/diploma_archive/blob/main/app/src/hooks/usePermission.ts"
click node_student_service "https://github.com/riadhlaroui/diploma_archive/blob/main/app/src/services/studentService.ts"
click node_academic_services "https://github.com/riadhlaroui/diploma_archive/blob/main/app/src/services/facultieService.ts"
click node_ocr_api "https://github.com/riadhlaroui/diploma_archive/blob/main/app/api/ocr/route.ts"
click node_gemini_ocr_api "https://github.com/riadhlaroui/diploma_archive/blob/main/app/api/ocr-gemini/route.ts"
click node_pocketbase "https://github.com/riadhlaroui/diploma_archive/blob/main/app/src/infrastructure/auth/pocketbaseClient.ts"
click node_archive_database "https://github.com/riadhlaroui/diploma_archive/blob/main/pocketbase/pocketbase_0.34.2_linux_amd64/pb_data/data.db"
click node_i18n "https://github.com/riadhlaroui/diploma_archive/blob/main/lib/i18n/i18n.ts"
click node_nginx "https://github.com/riadhlaroui/diploma_archive/blob/main/nginx/nginx.conf"
click node_container_stack "https://github.com/riadhlaroui/diploma_archive/blob/main/docker-compose.yml"

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_app_shell,node_auth_shell,node_main_shell,node_dashboard,node_student_records,node_bulk_import,node_student_form,node_document_upload,node_i18n toneBlue
class node_auth_api,node_auth_guard,node_route_middleware,node_authorization,node_student_service,node_academic_services,node_ocr_api,node_gemini_ocr_api toneAmber
class node_pocketbase,node_archive_database,node_gemini toneMint
class node_nginx,node_container_stack toneRose
```

## Components

### Next.js UI

- [App Router shell](https://github.com/riadhlaroui/diploma_archive/blob/main/app/layout.tsx): Next.js entry · `app/layout.tsx`
- [Authentication shell](https://github.com/riadhlaroui/diploma_archive/blob/main/app/(auth)/layout.tsx): route layout · `app/(auth)/layout.tsx`
- [Protected app shell](https://github.com/riadhlaroui/diploma_archive/blob/main/app/(main)/layout.tsx): route layout · Hosts main navigation and protected sections. · `app/(main)/layout.tsx`
- [Dashboard](https://github.com/riadhlaroui/diploma_archive/blob/main/app/(main)/dashboard/page.tsx): main route · `app/(main)/dashboard/page.tsx`
- [Student records](https://github.com/riadhlaroui/diploma_archive/blob/main/app/(main)/students/page.tsx): archive routes · Student CRUD, documents, and diploma printing. · `app/(main)/students/page.tsx`
- [Bulk student import](https://github.com/riadhlaroui/diploma_archive/blob/main/app/(main)/students/bulk-import/page.tsx): main route · `app/(main)/students/bulk-import/page.tsx`
- [Student form](https://github.com/riadhlaroui/diploma_archive/blob/main/components/StudentForm.jsx): UI component · `components/StudentForm.jsx`
- [Document upload & OCR UI](https://github.com/riadhlaroui/diploma_archive/blob/main/components/OCRUploader.tsx): UI components · `components/OCRUploader.tsx`
- [Arabic, English & French i18n](https://github.com/riadhlaroui/diploma_archive/blob/main/lib/i18n/i18n.ts): localization · `lib/i18n/i18n.ts`

### Application Services

- [Login & token refresh](https://github.com/riadhlaroui/diploma_archive/blob/main/app/api/auth/login/route.ts): Next API routes · Server boundary for PocketBase session operations. · `app/api/auth/login/route.ts`
- [Session guard](https://github.com/riadhlaroui/diploma_archive/blob/main/app/src/core/use-cases/ensureUserIsAuthenticated.ts): auth use case · `app/src/core/use-cases/ensureUserIsAuthenticated.ts`
- [Route middleware](https://github.com/riadhlaroui/diploma_archive/blob/main/middleware.ts): request guard · `middleware.ts`
- [Permission checks](https://github.com/riadhlaroui/diploma_archive/blob/main/app/src/hooks/usePermission.ts): authorization hook · Uses centrally declared permissions and permission groups. · `app/src/hooks/usePermission.ts`
- [Student data service](https://github.com/riadhlaroui/diploma_archive/blob/main/app/src/services/studentService.ts): PocketBase service · `app/src/services/studentService.ts`
- [Academic taxonomy services](https://github.com/riadhlaroui/diploma_archive/blob/main/app/src/services/facultieService.ts): PocketBase services · Faculty-to-specialty reference hierarchy. · `app/src/services/facultieService.ts`
- [OCR API](https://github.com/riadhlaroui/diploma_archive/blob/main/app/api/ocr/route.ts): Next API route · `app/api/ocr/route.ts`
- [Gemini OCR API](https://github.com/riadhlaroui/diploma_archive/blob/main/app/api/ocr-gemini/route.ts): Next API route · Keeps Gemini invocation server-side. · `app/api/ocr-gemini/route.ts`

### Backend & Integrations

- [PocketBase](https://github.com/riadhlaroui/diploma_archive/blob/main/app/src/infrastructure/auth/pocketbaseClient.ts): auth and collections backend · Provides authentication and archive data collections. · `app/src/infrastructure/auth/pocketbaseClient.ts`
- [PocketBase SQLite data](https://github.com/riadhlaroui/diploma_archive/blob/main/pocketbase/pocketbase_0.34.2_linux_amd64/pb_data/data.db): persisted state · `pocketbase/pocketbase_0.34.2_linux_amd64/pb_data/data.db`
- **Google Gemini**: external AI/OCR

### Deployment

- [Nginx reverse proxy](https://github.com/riadhlaroui/diploma_archive/blob/main/nginx/nginx.conf): edge proxy · `nginx/nginx.conf`
- [Docker Compose stack](https://github.com/riadhlaroui/diploma_archive/blob/main/docker-compose.yml): deployment composition · Runs the Next.js, Nginx, and PocketBase services. · `docker-compose.yml`

## Connections

- App Router shell → Authentication shell: partitions routes
- App Router shell → Protected app shell: partitions routes
- Protected app shell → Dashboard: hosts
- Protected app shell → Student records: hosts
- Student records → Bulk student import: supports
- Student records → Student form: uses
- Student records → Document upload & OCR UI: uploads documents
- Protected app shell → Permission checks: gates UI/actions
- Route middleware → Session guard: enforces session
- Session guard → PocketBase: validates session
- Login & token refresh → PocketBase: sign-in and refresh
- Student form → Student data service: creates and updates
- Student records → Student data service: reads archive records
- Student records → Academic taxonomy services: selects taxonomy
- Student data service → PocketBase: collection access
- Academic taxonomy services → PocketBase: collection access
- Document upload & OCR UI → OCR API: submits OCR
- Document upload & OCR UI → Gemini OCR API: submits AI OCR
- Gemini OCR API → Google Gemini: invokes
- PocketBase → PocketBase SQLite data: persists data
- Nginx reverse proxy → App Router shell: proxies requests
- Docker Compose stack → Nginx reverse proxy: runs
- Docker Compose stack → PocketBase: runs
- App Router shell → Arabic, English & French i18n: localizes UI
