# mt1504-coffee/backend architecture

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

- Interactive diagram: https://gitdiagram.com/mt1504-coffee/backend
- Repository: https://github.com/mt1504-coffee/backend

## Overview

Aseo UCP Backend is a Spring API for bathroom cleaning operations: users authenticate, submit cleaning records and incident reports, and administrators can review incidents and update their status. The API also supports user management, photo uploads, and password-reset email. The diagram follows the documented controller/service boundaries and the indexed repository, security, and notification references. Some implementations and configuration wiring were not excerpted, so their relationships are omitted or marked unverified rather than assumed.

Main entry points: [`src/main/java/com/ucp/aseo_ucp_backend/repository`](https://github.com/mt1504-coffee/backend/tree/main/src/main/java/com/ucp/aseo_ucp_backend/repository) (Persistence repositories), [`src/main/java/com/ucp/aseo_ucp_backend/service/impl/AuthServiceImpl.java`](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/AuthServiceImpl.java) (Authentication service), [`src/main/java/com/ucp/aseo_ucp_backend/dto`](https://github.com/mt1504-coffee/backend/tree/main/src/main/java/com/ucp/aseo_ucp_backend/dto) (API data contracts), [`src/main/java/com/ucp/aseo_ucp_backend/controller/AuthController.java`](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/controller/AuthController.java) (Authentication API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API workflows"]
  node_auth_api["Authentication API"]
  node_bathroom_api["Bathroom API"]
  node_cleaning_api["Cleaning API"]
  node_incident_api["Incident API"]
  node_user_api["User API"]
  node_api_dtos["API data contracts"]
  node_file_api["File API"]
  node_exception_handler["Exception handling"]
end

subgraph group_domain["Cleaning domain"]
  node_cleaning_service["Cleaning service"]
  node_bathroom_service["Bathroom service"]
  node_incident_service["Incident service"]
  node_user_entity["User records<br/>[User.java]"]
  node_bathroom_entity["Bathroom records<br/>[Bathroom.java]"]
  node_cleaning_entity["Cleaning records"]
  node_incident_entity["Incident records<br/>[Incident.java]"]
  node_repositories["Persistence repositories"]
end

subgraph group_identity["Identity and security"]
  node_auth_service["Authentication service"]
  node_user_service["User service"]
  node_security["JWT security"]
  node_user_details["User lookup"]
end

subgraph group_integrations["Storage and notifications"]
  node_file_service["File storage service"]
  node_local_storage["Local file storage"]
  node_cloudinary_storage["Cloudinary storage"]
  node_email_service["Email service"]
end

node_client(("API client"))
node_database[("Relational database")]
node_cloudinary{{"Cloudinary"}}
node_email_provider{{"Email provider"}}

node_client -->|"calls"| node_auth_api
node_client -.->|"calls"| node_bathroom_api
node_client -.->|"calls"| node_cleaning_api
node_client -.->|"calls"| node_incident_api
node_client -.->|"calls"| node_user_api
node_auth_api -->|"delegates to"| node_auth_service
node_bathroom_api -->|"delegates to"| node_bathroom_service
node_cleaning_api -->|"delegates to"| node_cleaning_service
node_incident_api -->|"delegates to"| node_incident_service
node_user_api -->|"delegates to"| node_user_service
node_auth_api -->|"accepts and returns"| node_api_dtos
node_cleaning_api -->|"uses"| node_api_dtos
node_incident_api -->|"uses"| node_api_dtos
node_user_api -->|"returns"| node_api_dtos
node_cleaning_service -.->|"persists via"| node_repositories
node_incident_service -.->|"persists via"| node_repositories
node_bathroom_service -.->|"persists via"| node_repositories
node_user_service -.->|"persists via"| node_repositories
node_repositories -.->|"reads and writes"| node_database
node_cleaning_entity -->|"references"| node_user_entity
node_cleaning_entity -->|"references"| node_bathroom_entity
node_incident_entity -->|"references"| node_user_entity
node_incident_entity -->|"references"| node_bathroom_entity
node_file_api -->|"delegates to"| node_file_service
node_file_service -.->|"implemented by"| node_local_storage
node_file_service -.->|"implemented by"| node_cloudinary_storage
node_cloudinary_storage -->|"uploads to"| node_cloudinary
node_auth_service -->|"uses"| node_repositories
node_auth_service -->|"creates tokens"| node_security
node_security -.->|"loads users"| node_user_details
node_user_details -->|"looks up users"| node_repositories
node_auth_service -->|"requests reset email"| node_email_service
node_email_service -.->|"sends messages"| node_email_provider
node_exception_handler -.->|"returns errors"| node_client

click node_auth_api "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/controller/AuthController.java"
click node_bathroom_api "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/controller/BathroomController.java"
click node_cleaning_api "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/controller/CleaningActivityController.java"
click node_incident_api "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/controller/IncidentController.java"
click node_user_api "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/controller/UserController.java"
click node_auth_service "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/AuthServiceImpl.java"
click node_user_service "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/UserServiceImpl.java"
click node_security "https://github.com/mt1504-coffee/backend/tree/main/src/main/java/com/ucp/aseo_ucp_backend/security"
click node_user_details "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/security/UserDetailsServiceImpl.java"
click node_cleaning_service "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/CleaningActivityServiceImpl.java"
click node_bathroom_service "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/BathroomServiceImpl.java"
click node_incident_service "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/IncidentServiceImpl.java"
click node_user_entity "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/entity/User.java"
click node_bathroom_entity "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/entity/Bathroom.java"
click node_cleaning_entity "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/entity/CleaningActivity.java"
click node_incident_entity "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/entity/Incident.java"
click node_api_dtos "https://github.com/mt1504-coffee/backend/tree/main/src/main/java/com/ucp/aseo_ucp_backend/dto"
click node_repositories "https://github.com/mt1504-coffee/backend/tree/main/src/main/java/com/ucp/aseo_ucp_backend/repository"
click node_file_api "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/controller/FileController.java"
click node_file_service "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/FileStorageService.java"
click node_local_storage "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/FileStorageServiceImpl.java"
click node_cloudinary_storage "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/CloudinaryFileStorageServiceImpl.java"
click node_email_service "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/EmailServiceImpl.java"
click node_exception_handler "https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/exception/GlobalExceptionHandler.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_api,node_bathroom_api,node_cleaning_api,node_incident_api,node_user_api,node_api_dtos,node_file_api,node_exception_handler,node_client toneBlue
class node_cleaning_service,node_bathroom_service,node_incident_service,node_user_entity,node_bathroom_entity,node_cleaning_entity,node_incident_entity,node_repositories,node_database toneAmber
class node_auth_service,node_user_service,node_security,node_user_details toneMint
class node_file_service,node_local_storage,node_cloudinary_storage,node_email_service toneRose
class node_cloudinary,node_email_provider toneIndigo
```

## Components

### API workflows

- [Authentication API](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/controller/AuthController.java): `src/main/java/com/ucp/aseo_ucp_backend/controller/AuthController.java`
- [Bathroom API](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/controller/BathroomController.java): `src/main/java/com/ucp/aseo_ucp_backend/controller/BathroomController.java`
- [Cleaning API](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/controller/CleaningActivityController.java): `src/main/java/com/ucp/aseo_ucp_backend/controller/CleaningActivityController.java`
- [Incident API](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/controller/IncidentController.java): `src/main/java/com/ucp/aseo_ucp_backend/controller/IncidentController.java`
- [User API](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/controller/UserController.java): `src/main/java/com/ucp/aseo_ucp_backend/controller/UserController.java`
- [API data contracts](https://github.com/mt1504-coffee/backend/tree/main/src/main/java/com/ucp/aseo_ucp_backend/dto): `src/main/java/com/ucp/aseo_ucp_backend/dto`
- [File API](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/controller/FileController.java): `src/main/java/com/ucp/aseo_ucp_backend/controller/FileController.java`
- [Exception handling](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/exception/GlobalExceptionHandler.java): `src/main/java/com/ucp/aseo_ucp_backend/exception/GlobalExceptionHandler.java`

### Cleaning domain

- [Cleaning service](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/CleaningActivityServiceImpl.java): `src/main/java/com/ucp/aseo_ucp_backend/service/impl/CleaningActivityServiceImpl.java`
- [Bathroom service](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/BathroomServiceImpl.java): `src/main/java/com/ucp/aseo_ucp_backend/service/impl/BathroomServiceImpl.java`
- [Incident service](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/IncidentServiceImpl.java): `src/main/java/com/ucp/aseo_ucp_backend/service/impl/IncidentServiceImpl.java`
- [User records](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/entity/User.java): `src/main/java/com/ucp/aseo_ucp_backend/entity/User.java`
- [Bathroom records](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/entity/Bathroom.java): `src/main/java/com/ucp/aseo_ucp_backend/entity/Bathroom.java`
- [Cleaning records](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/entity/CleaningActivity.java): `src/main/java/com/ucp/aseo_ucp_backend/entity/CleaningActivity.java`
- [Incident records](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/entity/Incident.java): `src/main/java/com/ucp/aseo_ucp_backend/entity/Incident.java`
- [Persistence repositories](https://github.com/mt1504-coffee/backend/tree/main/src/main/java/com/ucp/aseo_ucp_backend/repository): `src/main/java/com/ucp/aseo_ucp_backend/repository`

### Identity and security

- [Authentication service](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/AuthServiceImpl.java): `src/main/java/com/ucp/aseo_ucp_backend/service/impl/AuthServiceImpl.java`
- [User service](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/UserServiceImpl.java): `src/main/java/com/ucp/aseo_ucp_backend/service/impl/UserServiceImpl.java`
- [JWT security](https://github.com/mt1504-coffee/backend/tree/main/src/main/java/com/ucp/aseo_ucp_backend/security): `src/main/java/com/ucp/aseo_ucp_backend/security`
- [User lookup](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/security/UserDetailsServiceImpl.java): `src/main/java/com/ucp/aseo_ucp_backend/security/UserDetailsServiceImpl.java`

### Storage and notifications

- [File storage service](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/FileStorageService.java): `src/main/java/com/ucp/aseo_ucp_backend/service/FileStorageService.java`
- [Local file storage](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/FileStorageServiceImpl.java): `src/main/java/com/ucp/aseo_ucp_backend/service/impl/FileStorageServiceImpl.java`
- [Cloudinary storage](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/CloudinaryFileStorageServiceImpl.java): `src/main/java/com/ucp/aseo_ucp_backend/service/impl/CloudinaryFileStorageServiceImpl.java`
- [Email service](https://github.com/mt1504-coffee/backend/blob/main/src/main/java/com/ucp/aseo_ucp_backend/service/impl/EmailServiceImpl.java): `src/main/java/com/ucp/aseo_ucp_backend/service/impl/EmailServiceImpl.java`

### Other components

- **API client**
- **Relational database**
- **Cloudinary**
- **Email provider**

## Connections

- API client → Authentication API: calls (evidence: `src/main/java/com/ucp/aseo_ucp_backend/controller/AuthController.java`)
- API client → Bathroom API: calls (evidence: `src/main/java/com/ucp/aseo_ucp_backend/controller/BathroomController.java`)
- API client → Cleaning API: calls (evidence: `src/main/java/com/ucp/aseo_ucp_backend/controller/CleaningActivityController.java`)
- API client → Incident API: calls (evidence: `src/main/java/com/ucp/aseo_ucp_backend/controller/IncidentController.java`)
- API client → User API: calls (evidence: `src/main/java/com/ucp/aseo_ucp_backend/controller/UserController.java`)
- Authentication API → Authentication service: delegates to (evidence: `src/main/java/com/ucp/aseo_ucp_backend/controller/AuthController.java`)
- Bathroom API → Bathroom service: delegates to (evidence: `src/main/java/com/ucp/aseo_ucp_backend/controller/BathroomController.java`)
- Cleaning API → Cleaning service: delegates to (evidence: `src/main/java/com/ucp/aseo_ucp_backend/controller/CleaningActivityController.java`)
- Incident API → Incident service: delegates to (evidence: `src/main/java/com/ucp/aseo_ucp_backend/controller/IncidentController.java`)
- User API → User service: delegates to (evidence: `src/main/java/com/ucp/aseo_ucp_backend/controller/UserController.java`)
- Authentication API → API data contracts: accepts and returns (evidence: `src/main/java/com/ucp/aseo_ucp_backend/controller/AuthController.java`)
- Cleaning API → API data contracts: uses (evidence: `src/main/java/com/ucp/aseo_ucp_backend/controller/CleaningActivityController.java`)
- Incident API → API data contracts: uses (evidence: `src/main/java/com/ucp/aseo_ucp_backend/controller/IncidentController.java`)
- User API → API data contracts: returns (evidence: `src/main/java/com/ucp/aseo_ucp_backend/controller/UserController.java`)
- Cleaning service → Persistence repositories: persists via
- Incident service → Persistence repositories: persists via
- Bathroom service → Persistence repositories: persists via
- User service → Persistence repositories: persists via
- Persistence repositories → Relational database: reads and writes
- Cleaning records → User records: references (evidence: `src/main/java/com/ucp/aseo_ucp_backend/entity/CleaningActivity.java`)
- Cleaning records → Bathroom records: references (evidence: `src/main/java/com/ucp/aseo_ucp_backend/entity/CleaningActivity.java`)
- Incident records → User records: references (evidence: `src/main/java/com/ucp/aseo_ucp_backend/entity/Incident.java`)
- Incident records → Bathroom records: references (evidence: `src/main/java/com/ucp/aseo_ucp_backend/entity/Incident.java`)
- File API → File storage service: delegates to (evidence: `src/main/java/com/ucp/aseo_ucp_backend/controller/FileController.java`)
- File storage service → Local file storage: implemented by (evidence: `src/main/java/com/ucp/aseo_ucp_backend/service/impl/FileStorageServiceImpl.java`)
- File storage service → Cloudinary storage: implemented by (evidence: `src/main/java/com/ucp/aseo_ucp_backend/service/impl/CloudinaryFileStorageServiceImpl.java`)
- Cloudinary storage → Cloudinary: uploads to (evidence: `src/main/java/com/ucp/aseo_ucp_backend/service/impl/CloudinaryFileStorageServiceImpl.java`)
- Authentication service → Persistence repositories: uses (evidence: `src/main/java/com/ucp/aseo_ucp_backend/service/impl/AuthServiceImpl.java`)
- Authentication service → JWT security: creates tokens (evidence: `src/main/java/com/ucp/aseo_ucp_backend/service/impl/AuthServiceImpl.java`)
- JWT security → User lookup: loads users
- User lookup → Persistence repositories: looks up users (evidence: `src/main/java/com/ucp/aseo_ucp_backend/security/UserDetailsServiceImpl.java`)
- Authentication service → Email service: requests reset email (evidence: `src/main/java/com/ucp/aseo_ucp_backend/service/impl/AuthServiceImpl.java`)
- Email service → Email provider: sends messages
- Exception handling → API client: returns errors
