# hmmkez/tipiganan-backend architecture

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

- Interactive diagram: https://gitdiagram.com/hmmkez/tipiganan-backend
- Repository: https://github.com/hmmkez/tipiganan-backend

## Overview

TIPIGANAN is a Laravel REST API for an online repository of special and rare collections. Readers search and access theses, while staff manage thesis files, users, school-roster imports, citations and favorites; reporting and audit exports support administration. The sampled code confirms thesis OCR dispatch and extraction, roster synchronization, and cached reporting. The README also documents optional Meilisearch and Redis, plus audit and PDF report exports. Some controller and integration behavior is unsampled, so uncertain links are omitted rather than inferred.

Main entry points: [`routes/api.php`](https://github.com/hmmkez/tipiganan-backend/blob/main/routes/api.php) (API routing), [`app/Models/Thesis.php`](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Models/Thesis.php) (Thesis records), [`app/Http/Controllers/Api/ReportController.php`](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/ReportController.php) (Analytics and exports), [`app/Http/Controllers/Api/ThesisController.php`](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/ThesisController.php) (Thesis management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and accounts"]
  node_routes["API routing<br/>[api.php]"]
  node_auth["Authentication<br/>[AuthController.php]"]
  node_accounts["Account management<br/>[UserController.php]"]
  node_user_model[("User accounts<br/>[User.php]")]
end

subgraph group_repository["Thesis repository"]
  node_theses["Thesis management"]
  node_thesis_model[("Thesis records<br/>[Thesis.php]")]
  node_search["Thesis search"]
  node_search_service["Search service<br/>[SearchService.php]"]
  node_ocr_job["OCR job"]
  node_ocr_service["OCR extraction<br/>[OcrService.php]"]
  node_ocr_script["Node OCR script<br/>[extract.cjs]"]
  node_watermark["PDF watermarking"]
  node_citations["Citation records"]
  node_favorites["Favorites"]
end

subgraph group_school["School directory"]
  node_school_roster_api["Roster administration"]
  node_school_roster["Roster synchronization<br/>[SchoolRoster.php]"]
  node_school_directory["School directory"]
end

subgraph group_insights["Reports and audit"]
  node_reports["Analytics and exports"]
  node_audit_api["Audit log API"]
  node_audit_model[("Audit records<br/>[AuditLog.php]")]
  node_cache["Safe cache<br/>[SafeCache.php]"]
end

node_reader(("API users"))
node_meilisearch["Meilisearch"]
node_school_system["School system"]

node_reader -->|"calls API"| node_routes
node_routes -->|"routes to"| node_auth
node_routes -->|"routes to"| node_accounts
node_routes -->|"routes to"| node_theses
node_routes -->|"routes to"| node_search
node_routes -->|"routes to"| node_school_roster_api
node_routes -->|"routes to"| node_citations
node_routes -->|"routes to"| node_favorites
node_routes -->|"routes to"| node_reports
node_routes -->|"routes to"| node_audit_api
node_accounts -->|"updates accounts"| node_user_model
node_accounts -->|"records changes"| node_audit_model
node_theses -->|"manages records"| node_thesis_model
node_theses -->|"dispatches OCR"| node_ocr_job
node_ocr_job -->|"calls extraction"| node_ocr_service
node_ocr_job -->|"updates record"| node_thesis_model
node_ocr_service -->|"runs script"| node_ocr_script
node_theses -->|"uses watermark"| node_watermark
node_search -.->|"delegates search"| node_search_service
node_search_service -->|"searches records"| node_thesis_model
node_search_service -.->|"optionally indexes"| node_meilisearch
node_school_roster_api -->|"imports roster"| node_school_roster
node_school_roster -->|"updates accounts"| node_user_model
node_school_roster_api -.->|"selects directory"| node_school_directory
node_school_directory -.->|"checks membership"| node_school_system
node_citations -.->|"records citations"| node_thesis_model
node_favorites -.->|"stores favorites"| node_thesis_model
node_reports -->|"reads metrics"| node_thesis_model
node_reports -->|"reads accounts"| node_user_model
node_reports -->|"reads activity"| node_audit_model
node_reports -->|"caches results"| node_cache
node_audit_api -.->|"exports records"| node_audit_model

click node_routes "https://github.com/hmmkez/tipiganan-backend/blob/main/routes/api.php"
click node_auth "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/AuthController.php"
click node_accounts "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/UserController.php"
click node_user_model "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Models/User.php"
click node_theses "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/ThesisController.php"
click node_thesis_model "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Models/Thesis.php"
click node_search "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/SearchController.php"
click node_search_service "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Services/SearchService.php"
click node_ocr_job "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Jobs/ProcessThesisOcr.php"
click node_ocr_service "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Services/OcrService.php"
click node_ocr_script "https://github.com/hmmkez/tipiganan-backend/blob/main/ocr/extract.cjs"
click node_watermark "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Services/WatermarkService.php"
click node_school_roster_api "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/SchoolRosterController.php"
click node_school_roster "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Support/SchoolRoster.php"
click node_school_directory "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Support/SchoolDirectory/SchoolDirectory.php"
click node_citations "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/CitationController.php"
click node_favorites "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/FavoriteController.php"
click node_reports "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/ReportController.php"
click node_audit_api "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/AuditLogController.php"
click node_audit_model "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Models/AuditLog.php"
click node_cache "https://github.com/hmmkez/tipiganan-backend/blob/main/app/Support/SafeCache.php"

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_routes,node_auth,node_accounts,node_user_model,node_reader toneBlue
class node_theses,node_thesis_model,node_search,node_search_service,node_ocr_job,node_ocr_service,node_ocr_script,node_watermark,node_citations,node_favorites toneAmber
class node_school_roster_api,node_school_roster,node_school_directory toneMint
class node_reports,node_audit_api,node_audit_model,node_cache toneRose
class node_meilisearch,node_school_system toneIndigo
```

## Components

### API and accounts

- [API routing](https://github.com/hmmkez/tipiganan-backend/blob/main/routes/api.php): `routes/api.php`
- [Authentication](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/AuthController.php): `app/Http/Controllers/Api/AuthController.php`
- [Account management](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/UserController.php): `app/Http/Controllers/Api/UserController.php`
- [User accounts](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Models/User.php): `app/Models/User.php`

### Thesis repository

- [Thesis management](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/ThesisController.php): `app/Http/Controllers/Api/ThesisController.php`
- [Thesis records](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Models/Thesis.php): `app/Models/Thesis.php`
- [Thesis search](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/SearchController.php): `app/Http/Controllers/Api/SearchController.php`
- [Search service](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Services/SearchService.php): `app/Services/SearchService.php`
- [OCR job](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Jobs/ProcessThesisOcr.php): `app/Jobs/ProcessThesisOcr.php`
- [OCR extraction](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Services/OcrService.php): `app/Services/OcrService.php`
- [Node OCR script](https://github.com/hmmkez/tipiganan-backend/blob/main/ocr/extract.cjs): `ocr/extract.cjs`
- [PDF watermarking](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Services/WatermarkService.php): `app/Services/WatermarkService.php`
- [Citation records](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/CitationController.php): `app/Http/Controllers/Api/CitationController.php`
- [Favorites](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/FavoriteController.php): `app/Http/Controllers/Api/FavoriteController.php`

### School directory

- [Roster administration](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/SchoolRosterController.php): `app/Http/Controllers/Api/SchoolRosterController.php`
- [Roster synchronization](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Support/SchoolRoster.php): `app/Support/SchoolRoster.php`
- [School directory](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Support/SchoolDirectory/SchoolDirectory.php): `app/Support/SchoolDirectory/SchoolDirectory.php`

### Reports and audit

- [Analytics and exports](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/ReportController.php): `app/Http/Controllers/Api/ReportController.php`
- [Audit log API](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Http/Controllers/Api/AuditLogController.php): `app/Http/Controllers/Api/AuditLogController.php`
- [Audit records](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Models/AuditLog.php): `app/Models/AuditLog.php`
- [Safe cache](https://github.com/hmmkez/tipiganan-backend/blob/main/app/Support/SafeCache.php): `app/Support/SafeCache.php`

### Other components

- **API users**
- **Meilisearch**
- **School system**

## Connections

- API users → API routing: calls API (evidence: `routes/api.php`)
- API routing → Authentication: routes to (evidence: `routes/api.php`)
- API routing → Account management: routes to (evidence: `routes/api.php`)
- API routing → Thesis management: routes to (evidence: `routes/api.php`)
- API routing → Thesis search: routes to (evidence: `routes/api.php`)
- API routing → Roster administration: routes to (evidence: `routes/api.php`)
- API routing → Citation records: routes to (evidence: `routes/api.php`)
- API routing → Favorites: routes to (evidence: `routes/api.php`)
- API routing → Analytics and exports: routes to (evidence: `routes/api.php`)
- API routing → Audit log API: routes to (evidence: `routes/api.php`)
- Account management → User accounts: updates accounts (evidence: `app/Http/Controllers/Api/UserController.php`)
- Account management → Audit records: records changes (evidence: `app/Http/Controllers/Api/UserController.php`)
- Thesis management → Thesis records: manages records (evidence: `app/Http/Controllers/Api/ThesisController.php`)
- Thesis management → OCR job: dispatches OCR (evidence: `app/Http/Controllers/Api/ThesisController.php`)
- OCR job → OCR extraction: calls extraction (evidence: `app/Jobs/ProcessThesisOcr.php`)
- OCR job → Thesis records: updates record (evidence: `app/Jobs/ProcessThesisOcr.php`)
- OCR extraction → Node OCR script: runs script (evidence: `app/Services/OcrService.php`)
- Thesis management → PDF watermarking: uses watermark (evidence: `app/Http/Controllers/Api/ThesisController.php`)
- Thesis search → Search service: delegates search
- Search service → Thesis records: searches records (evidence: `app/Services/SearchService.php`)
- Search service → Meilisearch: optionally indexes (evidence: `README.md`)
- Roster administration → Roster synchronization: imports roster (evidence: `app/Http/Controllers/Api/SchoolRosterController.php`)
- Roster synchronization → User accounts: updates accounts (evidence: `app/Support/SchoolRoster.php`)
- Roster administration → School directory: selects directory
- School directory → School system: checks membership
- Citation records → Thesis records: records citations
- Favorites → Thesis records: stores favorites
- Analytics and exports → Thesis records: reads metrics (evidence: `app/Http/Controllers/Api/ReportController.php`)
- Analytics and exports → User accounts: reads accounts (evidence: `app/Http/Controllers/Api/ReportController.php`)
- Analytics and exports → Audit records: reads activity (evidence: `app/Http/Controllers/Api/ReportController.php`)
- Analytics and exports → Safe cache: caches results (evidence: `app/Http/Controllers/Api/ReportController.php`)
- Audit log API → Audit records: exports records
