# shaorankun/clarity-api architecture

> Architecture diagram of the GitHub repository shaorankun/clarity-api, 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/shaorankun/clarity-api
- Repository: https://github.com/shaorankun/clarity-api

## Overview

Clarity is a productivity backend: users manage tasks and personal focus sessions, with completed sessions feeding streaks and productivity statistics. A parallel collaborative-room workflow supports discovery, joining, owner-controlled focus/break timers, cached room state, and WebSocket broadcasts. The graph follows the documented controller–service–repository layers and sampled service calls; some feature wiring is based on README documentation because those implementations were not sampled.

Main entry points: [`src/main/java/com/clarity/backend/service/StudyRoomService.java`](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/StudyRoomService.java) (Study room service), [`src/main/java/com/clarity/backend/service/UserService.java`](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/UserService.java) (User service), [`src/main/java/com/clarity/backend/service/RedisRoomService.java`](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/RedisRoomService.java) (Redis room state), [`src/main/java/com/clarity/backend/service/RoomSessionService.java`](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/RoomSessionService.java) (Room timer service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API entry points"]
  node_usercontroller["Auth API"]
  node_taskcontroller["Task API"]
  node_sessioncontroller["Focus API"]
  node_statcontroller["Statistics API"]
  node_roomcontroller["Room REST API"]
  node_wscontroller["Room STOMP API"]
end

subgraph group_personal["Personal productivity"]
  node_taskservice["Task service<br/>[TaskService.java]"]
  node_focusservice["Focus session service"]
  node_streakservice["Streak service<br/>[StreakService.java]"]
  node_statservice["Statistics service<br/>[StatService.java]"]
end

subgraph group_rooms["Collaborative rooms"]
  node_roomservice["Study room service"]
  node_roommemberservice["Room membership"]
  node_roomsessionservice["Room timer service"]
  node_redisroom["Redis room state"]
end

subgraph group_identity["Identity and security"]
  node_userservice["User service<br/>[UserService.java]"]
  node_jwtservice["JWT service<br/>[JwtService.java]"]
  node_security["Request security<br/>[JwtAuthFilter.java]"]
  node_wssecurity["STOMP authentication"]
end

subgraph group_persistence["Persistence and state"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
end

node_client(("App client"))
node_roomtopic(("Room subscribers"))

node_client -->|"auth requests"| node_usercontroller
node_client -->|"manage tasks"| node_taskcontroller
node_client -->|"track focus"| node_sessioncontroller
node_client -->|"request stats"| node_statcontroller
node_client -->|"manage rooms"| node_roomcontroller
node_client -->|"timer commands"| node_wscontroller
node_usercontroller -->|"delegates"| node_userservice
node_taskcontroller -->|"delegates"| node_taskservice
node_sessioncontroller -->|"delegates"| node_focusservice
node_statcontroller -->|"delegates"| node_statservice
node_roomcontroller -->|"delegates"| node_roomservice
node_wscontroller -->|"dispatches"| node_roomsessionservice
node_userservice -->|"creates and checks tokens"| node_jwtservice
node_userservice -->|"blacklists refresh token"| node_redisroom
node_userservice -->|"leaves room on logout"| node_roomservice
node_security -->|"validates tokens"| node_jwtservice
node_wssecurity -->|"authenticates STOMP"| node_jwtservice
node_focusservice -->|"updates on completion"| node_streakservice
node_statservice -->|"reads session records"| node_postgres
node_focusservice -->|"reads and writes sessions"| node_postgres
node_taskservice -->|"manages task records"| node_postgres
node_streakservice -->|"reads and writes streaks"| node_postgres
node_userservice -->|"reads and writes users"| node_postgres
node_roomservice -->|"gets room members"| node_roommemberservice
node_roomservice -->|"creates room timer"| node_roomsessionservice
node_roomservice -->|"caches and retrieves state"| node_redisroom
node_roomsessionservice -->|"saves timer state"| node_redisroom
node_roomservice -->|"manages rooms and membership"| node_postgres
node_roomsessionservice -->|"reads and writes timer"| node_postgres
node_redisroom -->|"reads and writes cache"| node_redis
node_redisroom -->|"stores token blacklist"| node_redis
node_wscontroller -->|"broadcasts state"| node_roomtopic
node_roomtopic -->|"receives updates"| node_client

click node_usercontroller "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/controller/UserController.java"
click node_taskcontroller "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/controller/TaskController.java"
click node_sessioncontroller "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/controller/FocusSessionController.java"
click node_statcontroller "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/controller/StatController.java"
click node_roomcontroller "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/controller/StudyRoomController.java"
click node_wscontroller "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/controller/RoomWebSocketController.java"
click node_userservice "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/UserService.java"
click node_jwtservice "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/JwtService.java"
click node_security "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/security/JwtAuthFilter.java"
click node_wssecurity "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/security/WebSocketAuthInterceptor.java"
click node_taskservice "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/TaskService.java"
click node_focusservice "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/FocusSessionService.java"
click node_streakservice "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/StreakService.java"
click node_statservice "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/StatService.java"
click node_roomservice "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/StudyRoomService.java"
click node_roommemberservice "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/RoomMemberService.java"
click node_roomsessionservice "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/RoomSessionService.java"
click node_redisroom "https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/RedisRoomService.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_usercontroller,node_taskcontroller,node_sessioncontroller,node_statcontroller,node_roomcontroller,node_wscontroller,node_client toneBlue
class node_taskservice,node_focusservice,node_streakservice,node_statservice toneAmber
class node_roomservice,node_roommemberservice,node_roomsessionservice,node_redisroom toneMint
class node_userservice,node_jwtservice,node_security,node_wssecurity toneRose
class node_postgres,node_redis,node_roomtopic toneIndigo
```

## Components

### API entry points

- [Auth API](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/controller/UserController.java): `src/main/java/com/clarity/backend/controller/UserController.java`
- [Task API](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/controller/TaskController.java): `src/main/java/com/clarity/backend/controller/TaskController.java`
- [Focus API](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/controller/FocusSessionController.java): `src/main/java/com/clarity/backend/controller/FocusSessionController.java`
- [Statistics API](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/controller/StatController.java): `src/main/java/com/clarity/backend/controller/StatController.java`
- [Room REST API](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/controller/StudyRoomController.java): `src/main/java/com/clarity/backend/controller/StudyRoomController.java`
- [Room STOMP API](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/controller/RoomWebSocketController.java): `src/main/java/com/clarity/backend/controller/RoomWebSocketController.java`

### Personal productivity

- [Task service](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/TaskService.java): `src/main/java/com/clarity/backend/service/TaskService.java`
- [Focus session service](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/FocusSessionService.java): `src/main/java/com/clarity/backend/service/FocusSessionService.java`
- [Streak service](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/StreakService.java): `src/main/java/com/clarity/backend/service/StreakService.java`
- [Statistics service](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/StatService.java): `src/main/java/com/clarity/backend/service/StatService.java`

### Collaborative rooms

- [Study room service](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/StudyRoomService.java): `src/main/java/com/clarity/backend/service/StudyRoomService.java`
- [Room membership](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/RoomMemberService.java): `src/main/java/com/clarity/backend/service/RoomMemberService.java`
- [Room timer service](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/RoomSessionService.java): `src/main/java/com/clarity/backend/service/RoomSessionService.java`
- [Redis room state](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/RedisRoomService.java): `src/main/java/com/clarity/backend/service/RedisRoomService.java`

### Identity and security

- [User service](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/UserService.java): `src/main/java/com/clarity/backend/service/UserService.java`
- [JWT service](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/service/JwtService.java): `src/main/java/com/clarity/backend/service/JwtService.java`
- [Request security](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/security/JwtAuthFilter.java): `src/main/java/com/clarity/backend/security/JwtAuthFilter.java`
- [STOMP authentication](https://github.com/shaorankun/clarity-api/blob/master/src/main/java/com/clarity/backend/security/WebSocketAuthInterceptor.java): `src/main/java/com/clarity/backend/security/WebSocketAuthInterceptor.java`

### Persistence and state

- **PostgreSQL**
- **Redis**

### Other components

- **App client**
- **Room subscribers**

## Connections

- App client → Auth API: auth requests
- App client → Task API: manage tasks
- App client → Focus API: track focus
- App client → Statistics API: request stats
- App client → Room REST API: manage rooms
- App client → Room STOMP API: timer commands
- Auth API → User service: delegates
- Task API → Task service: delegates
- Focus API → Focus session service: delegates
- Statistics API → Statistics service: delegates
- Room REST API → Study room service: delegates
- Room STOMP API → Room timer service: dispatches
- User service → JWT service: creates and checks tokens
- User service → Redis room state: blacklists refresh token
- User service → Study room service: leaves room on logout
- Request security → JWT service: validates tokens
- STOMP authentication → JWT service: authenticates STOMP
- Focus session service → Streak service: updates on completion
- Statistics service → PostgreSQL: reads session records
- Focus session service → PostgreSQL: reads and writes sessions
- Task service → PostgreSQL: manages task records
- Streak service → PostgreSQL: reads and writes streaks
- User service → PostgreSQL: reads and writes users
- Study room service → Room membership: gets room members
- Study room service → Room timer service: creates room timer
- Study room service → Redis room state: caches and retrieves state
- Room timer service → Redis room state: saves timer state
- Study room service → PostgreSQL: manages rooms and membership
- Room timer service → PostgreSQL: reads and writes timer
- Redis room state → Redis: reads and writes cache
- Redis room state → Redis: stores token blacklist
- Room STOMP API → Room subscribers: broadcasts state
- Room subscribers → App client: receives updates