# narmi924/uptrail architecture

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

- Interactive diagram: https://gitdiagram.com/narmi924/uptrail
- Repository: https://github.com/narmi924/uptrail

## Overview

Uptrail is a staff-training workflow application: employees check eligibility and submit training applications, managers decide them, employees confirm completion and submit fee claims, and administrators register reimbursements and maintain the policies and catalogue. Annual entitlements track training-day and budget reservations, commitments, and reimbursements; signed-in users can also view a training calendar, while managers get team reports. The graph combines sampled service behavior with README-documented capabilities; links for unsampled subsystems reflect documented behavior rather than inspected call sites.

Main entry points: [`src/main/java/com/uptrail/claim/service/ClaimCommandService.java`](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/claim/service/ClaimCommandService.java) (Fee claims), [`src/main/java/com/uptrail/application/service/ApplicationCommandService.java`](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/application/service/ApplicationCommandService.java) (Application changes), [`src/main/java/com/uptrail/application/repository/CourseApplicationRepository.java`](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/application/repository/CourseApplicationRepository.java) (Application records), [`src/main/java/com/uptrail/entitlement/service/EntitlementService.java`](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/entitlement/service/EntitlementService.java) (Entitlement ledger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and people"]
  node_auth["Sign-in and security"]
  node_staff["Staff directory"]
  node_routing["Approval routing"]
end

subgraph group_training["Training workflow"]
  node_application_entry["Employee applications"]
  node_preview["Eligibility preview"]
  node_evaluator["Application evaluation"]
  node_application_commands["Application changes"]
  node_application_data["Application records"]
  node_manager_review["Manager decisions"]
  node_catalogue["Course catalogue"]
end

subgraph group_claims["Claims and ledger"]
  node_claims["Fee claims"]
  node_documents["Claim documents"]
  node_entitlement["Entitlement ledger"]
  node_ledger_view["Balance and history"]
end

subgraph group_insights["Calendar and reports"]
  node_calendar["Training calendar"]
  node_reports["Team reports"]
end

subgraph group_operations["Administration and mail"]
  node_admin["Administration"]
  node_audit["Audit trail<br/>[AuditService.java]"]
  node_notifications["Email outbox"]
  node_mail_transport["Mail transport<br/>[MailTransport.java]"]
end

node_employee(("Employee"))
node_manager(("Manager"))
node_administrator(("Administrator"))
node_application["Uptrail application"]
node_database[("MySQL database")]
node_mail_service["SMTP or file mail"]

node_employee -->|"signs in"| node_auth
node_manager -->|"signs in"| node_auth
node_administrator -->|"signs in"| node_auth
node_application -->|"configures access"| node_auth
node_employee -->|"submits application"| node_application_entry
node_application_entry -->|"checks eligibility"| node_preview
node_preview -->|"evaluates request"| node_evaluator
node_evaluator -->|"reads catalogue"| node_catalogue
node_preview -->|"checks conflicts"| node_application_data
node_application_entry -->|"updates application"| node_application_commands
node_application_commands -->|"rechecks eligibility"| node_evaluator
node_application_commands -->|"saves application"| node_application_data
node_application_commands -->|"reserves allowance"| node_entitlement
node_application_commands -->|"records change"| node_audit
node_application_commands -->|"queues email"| node_notifications
node_manager -->|"reviews application"| node_manager_review
node_manager_review -->|"reads applications"| node_application_data
node_manager_review -->|"reads staff"| node_staff
node_manager_review -->|"reads balances"| node_entitlement
node_manager_review -->|"decides application"| node_application_commands
node_employee -->|"claims course fee"| node_claims
node_manager -->|"reviews claim"| node_claims
node_administrator -->|"registers reimbursement"| node_claims
node_claims -->|"stores documents"| node_documents
node_claims -->|"updates ledger"| node_entitlement
node_claims -->|"records change"| node_audit
node_claims -->|"queues email"| node_notifications
node_employee -->|"views balance"| node_ledger_view
node_ledger_view -->|"reads movements"| node_entitlement
node_ledger_view -->|"reads course details"| node_application_data
node_employee -->|"views calendar"| node_calendar
node_manager -->|"views team reports"| node_reports
node_calendar -->|"reads courses"| node_application_data
node_calendar -->|"reads categories"| node_catalogue
node_reports -->|"reads attendance"| node_application_data
node_reports -->|"reads balances"| node_entitlement
node_administrator -->|"maintains operations"| node_admin
node_admin -->|"maintains staff"| node_staff
node_admin -->|"maintains routing"| node_routing
node_admin -->|"maintains catalogue"| node_catalogue
node_admin -->|"maintains allowances"| node_entitlement
node_admin -->|"checks audit and ledger"| node_audit
node_notifications -->|"dispatches messages"| node_mail_transport
node_mail_transport -->|"sends or writes"| node_mail_service
node_application_data -->|"reads and writes"| node_database
node_entitlement -->|"reads and writes"| node_database
node_claims -->|"reads and writes"| node_database
node_audit -->|"stores events"| node_database

click node_auth "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/identity/web/SecurityConfig.java"
click node_staff "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/organisation/service/EmployeeDirectoryService.java"
click node_routing "https://github.com/narmi924/uptrail/tree/main/src/main/java/com/uptrail/organisation/service"
click node_application_entry "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/application/web/EmployeeApplicationController.java"
click node_preview "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/application/service/ApplicationPreviewService.java"
click node_evaluator "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/application/service/ApplicationEvaluator.java"
click node_application_commands "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/application/service/ApplicationCommandService.java"
click node_application_data "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/application/repository/CourseApplicationRepository.java"
click node_manager_review "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/approval/service/ManagerApplicationService.java"
click node_catalogue "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/catalogue/service/CatalogueQueryService.java"
click node_calendar "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/reporting/service/CalendarQueryService.java"
click node_reports "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/reporting/service/ReportQueryService.java"
click node_claims "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/claim/service/ClaimCommandService.java"
click node_documents "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/claim/service/DocumentStorage.java"
click node_entitlement "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/entitlement/service/EntitlementService.java"
click node_ledger_view "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/entitlement/service/EntitlementQueryService.java"
click node_admin "https://github.com/narmi924/uptrail/tree/main/src/main/java/com/uptrail/admin/service"
click node_audit "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/audit/service/AuditService.java"
click node_notifications "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/notification/service/NotificationService.java"
click node_mail_transport "https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/notification/service/MailTransport.java"

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_auth,node_staff,node_routing toneBlue
class node_application_entry,node_preview,node_evaluator,node_application_commands,node_application_data,node_manager_review,node_catalogue,node_database toneAmber
class node_claims,node_documents,node_entitlement,node_ledger_view toneMint
class node_calendar,node_reports toneRose
class node_admin,node_audit,node_notifications,node_mail_transport,node_employee,node_manager,node_administrator,node_application,node_mail_service toneIndigo
```

## Components

### Identity and people

- [Sign-in and security](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/identity/web/SecurityConfig.java): `src/main/java/com/uptrail/identity/web/SecurityConfig.java`
- [Staff directory](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/organisation/service/EmployeeDirectoryService.java): `src/main/java/com/uptrail/organisation/service/EmployeeDirectoryService.java`
- [Approval routing](https://github.com/narmi924/uptrail/tree/main/src/main/java/com/uptrail/organisation/service): `src/main/java/com/uptrail/organisation/service`

### Training workflow

- [Employee applications](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/application/web/EmployeeApplicationController.java): `src/main/java/com/uptrail/application/web/EmployeeApplicationController.java`
- [Eligibility preview](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/application/service/ApplicationPreviewService.java): `src/main/java/com/uptrail/application/service/ApplicationPreviewService.java`
- [Application evaluation](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/application/service/ApplicationEvaluator.java): `src/main/java/com/uptrail/application/service/ApplicationEvaluator.java`
- [Application changes](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/application/service/ApplicationCommandService.java): `src/main/java/com/uptrail/application/service/ApplicationCommandService.java`
- [Application records](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/application/repository/CourseApplicationRepository.java): `src/main/java/com/uptrail/application/repository/CourseApplicationRepository.java`
- [Manager decisions](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/approval/service/ManagerApplicationService.java): `src/main/java/com/uptrail/approval/service/ManagerApplicationService.java`
- [Course catalogue](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/catalogue/service/CatalogueQueryService.java): `src/main/java/com/uptrail/catalogue/service/CatalogueQueryService.java`

### Claims and ledger

- [Fee claims](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/claim/service/ClaimCommandService.java): `src/main/java/com/uptrail/claim/service/ClaimCommandService.java`
- [Claim documents](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/claim/service/DocumentStorage.java): `src/main/java/com/uptrail/claim/service/DocumentStorage.java`
- [Entitlement ledger](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/entitlement/service/EntitlementService.java): `src/main/java/com/uptrail/entitlement/service/EntitlementService.java`
- [Balance and history](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/entitlement/service/EntitlementQueryService.java): `src/main/java/com/uptrail/entitlement/service/EntitlementQueryService.java`

### Calendar and reports

- [Training calendar](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/reporting/service/CalendarQueryService.java): `src/main/java/com/uptrail/reporting/service/CalendarQueryService.java`
- [Team reports](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/reporting/service/ReportQueryService.java): `src/main/java/com/uptrail/reporting/service/ReportQueryService.java`

### Administration and mail

- [Administration](https://github.com/narmi924/uptrail/tree/main/src/main/java/com/uptrail/admin/service): `src/main/java/com/uptrail/admin/service`
- [Audit trail](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/audit/service/AuditService.java): `src/main/java/com/uptrail/audit/service/AuditService.java`
- [Email outbox](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/notification/service/NotificationService.java): `src/main/java/com/uptrail/notification/service/NotificationService.java`
- [Mail transport](https://github.com/narmi924/uptrail/blob/main/src/main/java/com/uptrail/notification/service/MailTransport.java): `src/main/java/com/uptrail/notification/service/MailTransport.java`

### Other components

- **Employee**
- **Manager**
- **Administrator**
- **Uptrail application**
- **MySQL database**
- **SMTP or file mail**

## Connections

- Employee → Sign-in and security: signs in
- Manager → Sign-in and security: signs in
- Administrator → Sign-in and security: signs in
- Uptrail application → Sign-in and security: configures access
- Employee → Employee applications: submits application
- Employee applications → Eligibility preview: checks eligibility
- Eligibility preview → Application evaluation: evaluates request
- Application evaluation → Course catalogue: reads catalogue
- Eligibility preview → Application records: checks conflicts
- Employee applications → Application changes: updates application
- Application changes → Application evaluation: rechecks eligibility
- Application changes → Application records: saves application
- Application changes → Entitlement ledger: reserves allowance
- Application changes → Audit trail: records change
- Application changes → Email outbox: queues email
- Manager → Manager decisions: reviews application
- Manager decisions → Application records: reads applications
- Manager decisions → Staff directory: reads staff
- Manager decisions → Entitlement ledger: reads balances
- Manager decisions → Application changes: decides application
- Employee → Fee claims: claims course fee
- Manager → Fee claims: reviews claim
- Administrator → Fee claims: registers reimbursement
- Fee claims → Claim documents: stores documents
- Fee claims → Entitlement ledger: updates ledger
- Fee claims → Audit trail: records change
- Fee claims → Email outbox: queues email
- Employee → Balance and history: views balance
- Balance and history → Entitlement ledger: reads movements
- Balance and history → Application records: reads course details
- Employee → Training calendar: views calendar
- Manager → Team reports: views team reports
- Training calendar → Application records: reads courses
- Training calendar → Course catalogue: reads categories
- Team reports → Application records: reads attendance
- Team reports → Entitlement ledger: reads balances
- Administrator → Administration: maintains operations
- Administration → Staff directory: maintains staff
- Administration → Approval routing: maintains routing
- Administration → Course catalogue: maintains catalogue
- Administration → Entitlement ledger: maintains allowances
- Administration → Audit trail: checks audit and ledger
- Email outbox → Mail transport: dispatches messages
- Mail transport → SMTP or file mail: sends or writes
- Application records → MySQL database: reads and writes
- Entitlement ledger → MySQL database: reads and writes
- Fee claims → MySQL database: reads and writes
- Audit trail → MySQL database: stores events