# project-safeway/safeway-core-api architecture

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

- Interactive diagram: https://gitdiagram.com/project-safeway/safeway-core-api
- Repository: https://github.com/project-safeway/safeway-core-api

## Overview

SafeWay is a Spring REST backend for school-transport operators: authenticated users manage students, schools, guardians, vehicles, attendance, and itineraries. A representative route workflow accepts route changes, coordinates student and school stop services, validates stop addresses, and persists associations; routes can also be optimized using Google APIs. The README also documents RSA JWT authentication, student lifecycle events via RabbitMQ, address geocoding, and finance capabilities. Most edges below are backed by sampled callers or explicit README claims; unsampled modules are represented by their exact directories, with uncertain wiring omitted.

Main entry points: [`src/main/java/com/safeway/tech/api/controllers`](https://github.com/project-safeway/safeway-core-api/tree/master/src/main/java/com/safeway/tech/api/controllers) (REST endpoints), [`src/main/java/com/safeway/tech/service/services/RouteService.java`](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/RouteService.java) (Route orchestration), [`src/main/java/com/safeway/tech/service/services/RouteStudentService.java`](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/RouteStudentService.java) (Student stops), [`src/main/java/com/safeway/tech/service/services/RouteSchoolService.java`](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/RouteSchoolService.java) (School stops)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_rest_api["REST endpoints"]
  node_route_api["Route endpoints"]
  node_auth_api["Auth endpoints"]
end

subgraph group_school_ops["School Operations"]
  node_student_service["Student management"]
  node_guardian_service["Guardian management"]
  node_invitation_service["Guardian invitations"]
  node_school_services["School management"]
  node_attendance_services["Attendance"]
  node_transport_services["Transport management"]
  node_user_services["User profiles<br/>[UserService.java]"]
end

subgraph group_routing["Routing"]
  node_route_service["Route orchestration<br/>[RouteService.java]"]
  node_route_students["Student stops"]
  node_route_schools["School stops"]
  node_route_domain["Route records<br/>[Route.java]"]
  node_route_student_domain["Student stop records<br/>[RouteStudent.java]"]
  node_route_school_domain["School stop records<br/>[RouteSchool.java]"]
  node_optimization["Route optimization"]
  node_geocoding["Address geocoding"]
end

subgraph group_platform["Identity and Integrations"]
  node_auth_usecases["Auth use cases"]
  node_jwt["JWT issuance"]
  node_persistence[("JPA repositories")]
  node_student_events["Student events"]
  node_finance["Financial capabilities"]
end

node_operator(("Operator"))
node_google_api["Google Maps APIs"]
node_rabbitmq["RabbitMQ"]
node_financial_service["Financial service"]

node_operator -->|"uses"| node_rest_api
node_operator -->|"manages routes"| node_route_api
node_operator -->|"authenticates"| node_auth_api
node_route_api -->|"delegates"| node_route_service
node_route_service -->|"syncs stops"| node_route_students
node_route_service -->|"syncs stops"| node_route_schools
node_route_service -->|"saves routes"| node_persistence
node_route_students -->|"reads and writes"| node_persistence
node_route_schools -->|"reads and writes"| node_persistence
node_route_service -->|"updates"| node_route_domain
node_route_students -->|"creates links"| node_route_student_domain
node_route_schools -->|"creates links"| node_route_school_domain
node_route_students -->|"loads students"| node_student_service
node_route_schools -->|"loads schools"| node_school_services
node_rest_api -.->|"serves CRUD"| node_student_service
node_rest_api -.->|"serves requests"| node_guardian_service
node_rest_api -.->|"serves invitations"| node_invitation_service
node_rest_api -.->|"serves requests"| node_school_services
node_rest_api -.->|"records presence"| node_attendance_services
node_rest_api -.->|"serves requests"| node_transport_services
node_rest_api -.->|"serves profiles"| node_user_services
node_auth_api -->|"invokes"| node_auth_usecases
node_auth_usecases -.->|"issues tokens"| node_jwt
node_student_service -->|"reads and writes"| node_persistence
node_student_service -->|"publishes lifecycle"| node_student_events
node_student_events -->|"emits events"| node_rabbitmq
node_optimization -->|"optimizes routes"| node_google_api
node_geocoding -->|"geocodes addresses"| node_google_api
node_route_service -.->|"requests optimization"| node_optimization
node_finance -.->|"integrates"| node_financial_service

click node_rest_api "https://github.com/project-safeway/safeway-core-api/tree/master/src/main/java/com/safeway/tech/api/controllers"
click node_route_api "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/api/controllers/RouteController.java"
click node_auth_api "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/auth/infrastructure/entrypoint/http/AuthV2Controller.java"
click node_student_service "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/StudentService.java"
click node_guardian_service "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/GuardianService.java"
click node_invitation_service "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/GuardianInvitationService.java"
click node_school_services "https://github.com/project-safeway/safeway-core-api/tree/master/src/main/java/com/safeway/tech/service/services"
click node_attendance_services "https://github.com/project-safeway/safeway-core-api/tree/master/src/main/java/com/safeway/tech/service/services"
click node_transport_services "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/TransportService.java"
click node_user_services "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/UserService.java"
click node_route_service "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/RouteService.java"
click node_route_students "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/RouteStudentService.java"
click node_route_schools "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/RouteSchoolService.java"
click node_route_domain "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/domain/models/Route.java"
click node_route_student_domain "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/domain/models/RouteStudent.java"
click node_route_school_domain "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/domain/models/RouteSchool.java"
click node_optimization "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/RouteOptimizationService.java"
click node_geocoding "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/GeocodingService.java"
click node_auth_usecases "https://github.com/project-safeway/safeway-core-api/tree/master/src/main/java/com/safeway/tech/auth/core/application"
click node_jwt "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/auth/infrastructure/security/JwtTokenIssuerAdapter.java"
click node_persistence "https://github.com/project-safeway/safeway-core-api/tree/master/src/main/java/com/safeway/tech/repository"
click node_student_events "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/infra/messaging/publishers/EventPublisher.java"
click node_finance "https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/StudentFinancialService.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_rest_api,node_route_api,node_auth_api toneBlue
class node_student_service,node_guardian_service,node_invitation_service,node_school_services,node_attendance_services,node_transport_services,node_user_services toneAmber
class node_route_service,node_route_students,node_route_schools,node_route_domain,node_route_student_domain,node_route_school_domain,node_optimization,node_geocoding,node_google_api toneMint
class node_auth_usecases,node_jwt,node_persistence,node_student_events,node_finance toneRose
class node_operator,node_rabbitmq,node_financial_service toneIndigo
```

## Components

### REST API

- [REST endpoints](https://github.com/project-safeway/safeway-core-api/tree/master/src/main/java/com/safeway/tech/api/controllers): `src/main/java/com/safeway/tech/api/controllers`
- [Route endpoints](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/api/controllers/RouteController.java): `src/main/java/com/safeway/tech/api/controllers/RouteController.java`
- [Auth endpoints](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/auth/infrastructure/entrypoint/http/AuthV2Controller.java): `src/main/java/com/safeway/tech/auth/infrastructure/entrypoint/http/AuthV2Controller.java`

### School Operations

- [Student management](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/StudentService.java): `src/main/java/com/safeway/tech/service/services/StudentService.java`
- [Guardian management](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/GuardianService.java): `src/main/java/com/safeway/tech/service/services/GuardianService.java`
- [Guardian invitations](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/GuardianInvitationService.java): `src/main/java/com/safeway/tech/service/services/GuardianInvitationService.java`
- [School management](https://github.com/project-safeway/safeway-core-api/tree/master/src/main/java/com/safeway/tech/service/services): `src/main/java/com/safeway/tech/service/services`
- [Attendance](https://github.com/project-safeway/safeway-core-api/tree/master/src/main/java/com/safeway/tech/service/services): `src/main/java/com/safeway/tech/service/services`
- [Transport management](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/TransportService.java): `src/main/java/com/safeway/tech/service/services/TransportService.java`
- [User profiles](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/UserService.java): `src/main/java/com/safeway/tech/service/services/UserService.java`

### Routing

- [Route orchestration](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/RouteService.java): `src/main/java/com/safeway/tech/service/services/RouteService.java`
- [Student stops](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/RouteStudentService.java): `src/main/java/com/safeway/tech/service/services/RouteStudentService.java`
- [School stops](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/RouteSchoolService.java): `src/main/java/com/safeway/tech/service/services/RouteSchoolService.java`
- [Route records](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/domain/models/Route.java): `src/main/java/com/safeway/tech/domain/models/Route.java`
- [Student stop records](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/domain/models/RouteStudent.java): `src/main/java/com/safeway/tech/domain/models/RouteStudent.java`
- [School stop records](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/domain/models/RouteSchool.java): `src/main/java/com/safeway/tech/domain/models/RouteSchool.java`
- [Route optimization](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/RouteOptimizationService.java): `src/main/java/com/safeway/tech/service/services/RouteOptimizationService.java`
- [Address geocoding](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/GeocodingService.java): `src/main/java/com/safeway/tech/service/services/GeocodingService.java`

### Identity and Integrations

- [Auth use cases](https://github.com/project-safeway/safeway-core-api/tree/master/src/main/java/com/safeway/tech/auth/core/application): `src/main/java/com/safeway/tech/auth/core/application`
- [JWT issuance](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/auth/infrastructure/security/JwtTokenIssuerAdapter.java): `src/main/java/com/safeway/tech/auth/infrastructure/security/JwtTokenIssuerAdapter.java`
- [JPA repositories](https://github.com/project-safeway/safeway-core-api/tree/master/src/main/java/com/safeway/tech/repository): `src/main/java/com/safeway/tech/repository`
- [Student events](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/infra/messaging/publishers/EventPublisher.java): `src/main/java/com/safeway/tech/infra/messaging/publishers/EventPublisher.java`
- [Financial capabilities](https://github.com/project-safeway/safeway-core-api/blob/master/src/main/java/com/safeway/tech/service/services/StudentFinancialService.java): `src/main/java/com/safeway/tech/service/services/StudentFinancialService.java`

### Other components

- **Operator**
- **Google Maps APIs**
- **RabbitMQ**
- **Financial service**

## Connections

- Operator → REST endpoints: uses (evidence: `README.md`)
- Operator → Route endpoints: manages routes (evidence: `README.md`)
- Operator → Auth endpoints: authenticates (evidence: `README.md`)
- Route endpoints → Route orchestration: delegates (evidence: `src/main/java/com/safeway/tech/api/controllers/RouteController.java`)
- Route orchestration → Student stops: syncs stops (evidence: `src/main/java/com/safeway/tech/service/services/RouteService.java`)
- Route orchestration → School stops: syncs stops (evidence: `src/main/java/com/safeway/tech/service/services/RouteService.java`)
- Route orchestration → JPA repositories: saves routes (evidence: `src/main/java/com/safeway/tech/service/services/RouteService.java`)
- Student stops → JPA repositories: reads and writes (evidence: `src/main/java/com/safeway/tech/service/services/RouteStudentService.java`)
- School stops → JPA repositories: reads and writes (evidence: `src/main/java/com/safeway/tech/service/services/RouteSchoolService.java`)
- Route orchestration → Route records: updates (evidence: `src/main/java/com/safeway/tech/service/services/RouteService.java`)
- Student stops → Student stop records: creates links (evidence: `src/main/java/com/safeway/tech/service/services/RouteStudentService.java`)
- School stops → School stop records: creates links (evidence: `src/main/java/com/safeway/tech/service/services/RouteSchoolService.java`)
- Student stops → Student management: loads students (evidence: `src/main/java/com/safeway/tech/service/services/RouteStudentService.java`)
- School stops → School management: loads schools (evidence: `src/main/java/com/safeway/tech/service/services/RouteSchoolService.java`)
- REST endpoints → Student management: serves CRUD (evidence: `src/main/java/com/safeway/tech/api/controllers/StudentController.java`)
- REST endpoints → Guardian management: serves requests (evidence: `src/main/java/com/safeway/tech/api/controllers/StudentController.java`)
- REST endpoints → Guardian invitations: serves invitations (evidence: `src/main/java/com/safeway/tech/api/controllers/GuardianInvitationController.java`)
- REST endpoints → School management: serves requests (evidence: `src/main/java/com/safeway/tech/api/controllers/RouteController.java`)
- REST endpoints → Attendance: records presence (evidence: `src/main/java/com/safeway/tech/api/controllers/RouteController.java`)
- REST endpoints → Transport management: serves requests
- REST endpoints → User profiles: serves profiles
- Auth endpoints → Auth use cases: invokes (evidence: `src/main/java/com/safeway/tech/auth/infrastructure/entrypoint/http/AuthV2Controller.java`)
- Auth use cases → JWT issuance: issues tokens
- Student management → JPA repositories: reads and writes (evidence: `src/main/java/com/safeway/tech/service/services/StudentService.java`)
- Student management → Student events: publishes lifecycle (evidence: `src/main/java/com/safeway/tech/service/services/StudentService.java`)
- Student events → RabbitMQ: emits events (evidence: `README.md`)
- Route optimization → Google Maps APIs: optimizes routes (evidence: `README.md`)
- Address geocoding → Google Maps APIs: geocodes addresses (evidence: `README.md`)
- Route orchestration → Route optimization: requests optimization
- Financial capabilities → Financial service: integrates