How shaorankun/clarity-api works
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: StudyRoomService.java Study room service · UserService.java User service · RedisRoomService.java Redis room state · RoomSessionService.java Room timer service
Components 22
API entry points
- Auth API
src/main/java/com/clarity/backend/controller/UserController.java - Task API
src/main/java/com/clarity/backend/controller/TaskController.java - Focus API
src/main/java/com/clarity/backend/controller/FocusSessionController.java - Statistics API
src/main/java/com/clarity/backend/controller/StatController.java - Room REST API
src/main/java/com/clarity/backend/controller/StudyRoomController.java - Room STOMP API
src/main/java/com/clarity/backend/controller/RoomWebSocketController.java
Personal productivity
- Task service
src/main/java/com/clarity/backend/service/TaskService.java - Focus session service
src/main/java/com/clarity/backend/service/FocusSessionService.java - Streak service
src/main/java/com/clarity/backend/service/StreakService.java - Statistics service
src/main/java/com/clarity/backend/service/StatService.java
Collaborative rooms
- Study room service
src/main/java/com/clarity/backend/service/StudyRoomService.java - Room membership
src/main/java/com/clarity/backend/service/RoomMemberService.java - Room timer service
src/main/java/com/clarity/backend/service/RoomSessionService.java - Redis room state
src/main/java/com/clarity/backend/service/RedisRoomService.java
Identity and security
- User service
src/main/java/com/clarity/backend/service/UserService.java - JWT service
src/main/java/com/clarity/backend/service/JwtService.java - Request security
src/main/java/com/clarity/backend/security/JwtAuthFilter.java - STOMP authentication
src/main/java/com/clarity/backend/security/WebSocketAuthInterceptor.java
Persistence and state
- PostgreSQL
- Redis
Other components
- App client
- Room subscribers
Connections 33
- 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