# min-thant794/usermanagementsystem architecture

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

- Interactive diagram: https://gitdiagram.com/min-thant794/usermanagementsystem
- Repository: https://github.com/min-thant794/usermanagementsystem

## Overview

This Spring Boot REST API serves a React account workspace and administrator workspace. Its main flow is registration or sign-in (including Google), then verified, session-based JWT access to profile, password, photo, and session operations; administrators can manage users and inspect audit activity. Services coordinate PostgreSQL-backed repositories, cache behavior, email, and Cloudinary. The README also documents rate limiting, Redis caching, and scheduled token cleanup; those branches are shown at directory-level paths because their source was not sampled. Edges use only excerpted calls or explicit README relationships.

Main entry points: [`src/main/java/com/minthanttun/usermanagementsystem/auth/AuthService.java`](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/auth/AuthService.java) (Signup & login), [`src/main/java/com/minthanttun/usermanagementsystem/user/UserService.java`](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/user/UserService.java) (Profile & passwords), [`src/main/java/com/minthanttun/usermanagementsystem/UsermanagementsystemApplication.java`](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/UsermanagementsystemApplication.java) (Spring REST API), [`src/main/java/com/minthanttun/usermanagementsystem/auth/EmailVerificationService.java`](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/auth/EmailVerificationService.java) (Email verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_auth["Identity &amp; sessions"]
  node_authctrl["Auth endpoints"]
  node_authsvc["Signup &amp; login<br/>[AuthService.java]"]
  node_verification["Email verification"]
  node_email["Email delivery<br/>[EmailService.java]"]
  node_tokens["Refresh sessions<br/>[TokenIssuer.java]"]
  node_tokenhash["Token hashing<br/>[TokenHasher.java]"]
  node_oauth["Google sign-in"]
  node_sessionctrl["Session endpoints"]
  node_sessionmeta["Session metadata"]
end

subgraph group_account["Account management"]
  node_userctrl["Profile endpoints"]
  node_usersvc["Profile &amp; passwords<br/>[UserService.java]"]
  node_photos["Profile photos"]
end

subgraph group_admin["Administration &amp; audit"]
  node_adminctrl["Admin endpoints"]
  node_adminsvc["User administration"]
  node_auditctrl["Audit endpoints"]
  node_auditsvc["Audit recording<br/>[AuditService.java]"]
end

subgraph group_platform["Security &amp; infrastructure"]
  node_api["Spring REST API"]
  node_userrepo[("User persistence")]
  node_userentity["User account model<br/>[User.java]"]
  node_tokenrepo[("Refresh-token store")]
  node_auditrepo[("Audit log store")]
  node_security["JWT &amp; request security"]
  node_ratelimit["Rate limiting"]
  node_cache[("Redis caching")]
  node_cleanup["Token cleanup"]
end

node_browser(("Browser client"))
node_mailservice["SMTP provider"]
node_cloudinary["Cloudinary"]
node_postgres[("PostgreSQL")]
node_redis[("Redis / Valkey")]

node_browser -->|"sends requests"| node_api
node_api -->|"persists data"| node_postgres
node_api -->|"uses cache"| node_redis
node_api -->|"sends mail"| node_mailservice
node_api -->|"stores photos"| node_cloudinary
node_authctrl -.->|"delegates auth"| node_authsvc
node_authsvc -->|"reads and saves"| node_userrepo
node_authsvc -->|"starts verification"| node_verification
node_authsvc -->|"hashes tokens"| node_tokenhash
node_authsvc -->|"issues sessions"| node_tokens
node_authsvc -->|"rotates tokens"| node_tokenrepo
node_verification -->|"sends verification"| node_email
node_verification -->|"updates account"| node_userrepo
node_oauth -->|"loads identity"| node_userrepo
node_sessionctrl -->|"reads and revokes"| node_tokenrepo
node_sessionctrl -->|"hashes current token"| node_tokenhash
node_sessionctrl -->|"describes location"| node_sessionmeta
node_userctrl -.->|"delegates profile"| node_usersvc
node_usersvc -->|"reads and saves"| node_userrepo
node_usersvc -->|"uploads or deletes"| node_photos
node_usersvc -->|"requests verification"| node_verification
node_usersvc -.->|"revokes sessions"| node_tokenrepo
node_adminctrl -.->|"delegates admin work"| node_adminsvc
node_adminsvc -->|"searches and updates"| node_userrepo
node_adminsvc -->|"records changes"| node_auditsvc
node_adminsvc -->|"requests verification"| node_verification
node_auditctrl -.->|"queries audit"| node_auditsvc
node_auditsvc -->|"stores audit logs"| node_auditrepo
node_security -.->|"applies filters"| node_ratelimit
node_cleanup -.->|"cleans expired tokens"| node_tokenrepo

click node_api "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/UsermanagementsystemApplication.java"
click node_authctrl "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/auth/AuthController.java"
click node_authsvc "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/auth/AuthService.java"
click node_verification "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/auth/EmailVerificationService.java"
click node_email "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/auth/EmailService.java"
click node_tokens "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/security/jwt/TokenIssuer.java"
click node_tokenhash "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/security/jwt/TokenHasher.java"
click node_oauth "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/security/oauth2/CustomOidcUserService.java"
click node_sessionctrl "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/auth/SessionService.java"
click node_sessionmeta "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/security/session/GeoLocationService.java"
click node_userctrl "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/user/UserController.java"
click node_usersvc "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/user/UserService.java"
click node_photos "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/user/ProfileImageService.java"
click node_adminctrl "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/admin/AdminUserController.java"
click node_adminsvc "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/admin/AdminUserService.java"
click node_auditctrl "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/admin/AdminAuditLogController.java"
click node_auditsvc "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/audit/AuditService.java"
click node_userrepo "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/user/UserRepository.java"
click node_userentity "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/user/User.java"
click node_tokenrepo "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/auth/RefreshTokenRepository.java"
click node_auditrepo "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/audit/AuditLogRepository.java"
click node_security "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/config/SecurityConfig.java"
click node_ratelimit "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/security/ratelimit/RateLimitFilter.java"
click node_cache "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/config/RedisCacheConfig.java"
click node_cleanup "https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/common/TokenCleanupJob.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_authctrl,node_authsvc,node_verification,node_email,node_tokens,node_tokenhash,node_oauth,node_sessionctrl,node_sessionmeta,node_browser toneBlue
class node_userctrl,node_usersvc,node_photos,node_postgres,node_redis toneAmber
class node_adminctrl,node_adminsvc,node_auditctrl,node_auditsvc toneMint
class node_api,node_userrepo,node_userentity,node_tokenrepo,node_auditrepo,node_security,node_ratelimit,node_cache,node_cleanup toneRose
class node_mailservice,node_cloudinary toneIndigo
```

## Components

### Identity & sessions

- [Auth endpoints](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/auth/AuthController.java): `src/main/java/com/minthanttun/usermanagementsystem/auth/AuthController.java`
- [Signup & login](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/auth/AuthService.java): `src/main/java/com/minthanttun/usermanagementsystem/auth/AuthService.java`
- [Email verification](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/auth/EmailVerificationService.java): `src/main/java/com/minthanttun/usermanagementsystem/auth/EmailVerificationService.java`
- [Email delivery](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/auth/EmailService.java): `src/main/java/com/minthanttun/usermanagementsystem/auth/EmailService.java`
- [Refresh sessions](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/security/jwt/TokenIssuer.java): `src/main/java/com/minthanttun/usermanagementsystem/security/jwt/TokenIssuer.java`
- [Token hashing](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/security/jwt/TokenHasher.java): `src/main/java/com/minthanttun/usermanagementsystem/security/jwt/TokenHasher.java`
- [Google sign-in](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/security/oauth2/CustomOidcUserService.java): `src/main/java/com/minthanttun/usermanagementsystem/security/oauth2/CustomOidcUserService.java`
- [Session endpoints](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/auth/SessionService.java): `src/main/java/com/minthanttun/usermanagementsystem/auth/SessionService.java`
- [Session metadata](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/security/session/GeoLocationService.java): `src/main/java/com/minthanttun/usermanagementsystem/security/session/GeoLocationService.java`

### Account management

- [Profile endpoints](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/user/UserController.java): `src/main/java/com/minthanttun/usermanagementsystem/user/UserController.java`
- [Profile & passwords](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/user/UserService.java): `src/main/java/com/minthanttun/usermanagementsystem/user/UserService.java`
- [Profile photos](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/user/ProfileImageService.java): `src/main/java/com/minthanttun/usermanagementsystem/user/ProfileImageService.java`

### Administration & audit

- [Admin endpoints](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/admin/AdminUserController.java): `src/main/java/com/minthanttun/usermanagementsystem/admin/AdminUserController.java`
- [User administration](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/admin/AdminUserService.java): `src/main/java/com/minthanttun/usermanagementsystem/admin/AdminUserService.java`
- [Audit endpoints](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/admin/AdminAuditLogController.java): `src/main/java/com/minthanttun/usermanagementsystem/admin/AdminAuditLogController.java`
- [Audit recording](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/audit/AuditService.java): `src/main/java/com/minthanttun/usermanagementsystem/audit/AuditService.java`

### Security & infrastructure

- [Spring REST API](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/UsermanagementsystemApplication.java): `src/main/java/com/minthanttun/usermanagementsystem/UsermanagementsystemApplication.java`
- [User persistence](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/user/UserRepository.java): `src/main/java/com/minthanttun/usermanagementsystem/user/UserRepository.java`
- [User account model](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/user/User.java): `src/main/java/com/minthanttun/usermanagementsystem/user/User.java`
- [Refresh-token store](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/auth/RefreshTokenRepository.java): `src/main/java/com/minthanttun/usermanagementsystem/auth/RefreshTokenRepository.java`
- [Audit log store](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/audit/AuditLogRepository.java): `src/main/java/com/minthanttun/usermanagementsystem/audit/AuditLogRepository.java`
- [JWT & request security](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/config/SecurityConfig.java): `src/main/java/com/minthanttun/usermanagementsystem/config/SecurityConfig.java`
- [Rate limiting](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/security/ratelimit/RateLimitFilter.java): `src/main/java/com/minthanttun/usermanagementsystem/security/ratelimit/RateLimitFilter.java`
- [Redis caching](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/config/RedisCacheConfig.java): `src/main/java/com/minthanttun/usermanagementsystem/config/RedisCacheConfig.java`
- [Token cleanup](https://github.com/min-thant794/usermanagementsystem/blob/main/src/main/java/com/minthanttun/usermanagementsystem/common/TokenCleanupJob.java): `src/main/java/com/minthanttun/usermanagementsystem/common/TokenCleanupJob.java`

### Other components

- **Browser client**
- **SMTP provider**
- **Cloudinary**
- **PostgreSQL**
- **Redis / Valkey**

## Connections

- Browser client → Spring REST API: sends requests
- Spring REST API → PostgreSQL: persists data
- Spring REST API → Redis / Valkey: uses cache
- Spring REST API → SMTP provider: sends mail
- Spring REST API → Cloudinary: stores photos
- Auth endpoints → Signup & login: delegates auth
- Signup & login → User persistence: reads and saves (evidence: `src/main/java/com/minthanttun/usermanagementsystem/auth/AuthService.java`)
- Signup & login → Email verification: starts verification (evidence: `src/main/java/com/minthanttun/usermanagementsystem/auth/AuthService.java`)
- Signup & login → Token hashing: hashes tokens (evidence: `src/main/java/com/minthanttun/usermanagementsystem/auth/AuthService.java`)
- Signup & login → Refresh sessions: issues sessions (evidence: `src/main/java/com/minthanttun/usermanagementsystem/auth/AuthService.java`)
- Signup & login → Refresh-token store: rotates tokens (evidence: `src/main/java/com/minthanttun/usermanagementsystem/auth/AuthService.java`)
- Email verification → Email delivery: sends verification (evidence: `src/main/java/com/minthanttun/usermanagementsystem/auth/EmailVerificationService.java`)
- Email verification → User persistence: updates account (evidence: `src/main/java/com/minthanttun/usermanagementsystem/auth/EmailVerificationService.java`)
- Google sign-in → User persistence: loads identity (evidence: `src/main/java/com/minthanttun/usermanagementsystem/security/oauth2/CustomOidcUserService.java`)
- Session endpoints → Refresh-token store: reads and revokes (evidence: `src/main/java/com/minthanttun/usermanagementsystem/auth/SessionService.java`)
- Session endpoints → Token hashing: hashes current token (evidence: `src/main/java/com/minthanttun/usermanagementsystem/auth/SessionService.java`)
- Session endpoints → Session metadata: describes location (evidence: `src/main/java/com/minthanttun/usermanagementsystem/auth/SessionService.java`)
- Profile endpoints → Profile & passwords: delegates profile (evidence: `src/main/java/com/minthanttun/usermanagementsystem/user/UserController.java`)
- Profile & passwords → User persistence: reads and saves (evidence: `src/main/java/com/minthanttun/usermanagementsystem/user/UserService.java`)
- Profile & passwords → Profile photos: uploads or deletes (evidence: `src/main/java/com/minthanttun/usermanagementsystem/user/UserService.java`)
- Profile & passwords → Email verification: requests verification (evidence: `src/main/java/com/minthanttun/usermanagementsystem/user/UserService.java`)
- Profile & passwords → Refresh-token store: revokes sessions
- Admin endpoints → User administration: delegates admin work (evidence: `src/main/java/com/minthanttun/usermanagementsystem/admin/AdminUserController.java`)
- User administration → User persistence: searches and updates (evidence: `src/main/java/com/minthanttun/usermanagementsystem/admin/AdminUserService.java`)
- User administration → Audit recording: records changes (evidence: `src/main/java/com/minthanttun/usermanagementsystem/admin/AdminUserService.java`)
- User administration → Email verification: requests verification (evidence: `src/main/java/com/minthanttun/usermanagementsystem/admin/AdminUserService.java`)
- Audit endpoints → Audit recording: queries audit
- Audit recording → Audit log store: stores audit logs (evidence: `src/main/java/com/minthanttun/usermanagementsystem/audit/AuditService.java`)
- JWT & request security → Rate limiting: applies filters
- Token cleanup → Refresh-token store: cleans expired tokens
