# run-us/run-us-server architecture

> Architecture diagram of the GitHub repository run-us/run-us-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/run-us/run-us-server
- Repository: https://github.com/run-us/run-us-server

## Overview

##### Main Components

a. API Layer (Controllers):
- Auth/User Management (`AuthController`, `UserController`)
- Crew Management (`CrewController`)
- Running Management (`RunController`, `LiveRunningController`)
- Record Management (`RunRecordController`)

b. Service Layer:
- User Services (Authentication, Authorization)
- Crew Services (Crew management, membership)
- Running Services (Live running, running records)
- WebSocket Services (Real-time running updates)

c. Data Layer:
- JPA Repositories
- Redis Cache
- In-Memory Storage

##### Architecture Patterns to Highlight

a. Domain-Driven Design (DDD):
- Clear boundaries between domains (user, crew, running)
- Domain models and their relationships

b. Clean Architecture:
- Controllers → UseCases → Services → Repositories
- Dependency flow

##### Specific Components and Their Relationships

**[Client Applications]**
- ↓
**[Load Balancer/API Gateway]**
- ↓
**[API Layer]**
- REST Controllers
- WebSocket Controllers
- ↓
**[Service Layer]**
- Authentication/Authorization
- Crew Management
- Running Management
- Record Management
- ↓
**[Domain Layer]**
- User Domain
- Crew Domain
- Running Domain
- ↓
**[Persistence Layer]**
- JPA Repositories
- Redis Cache
- In-Memory Storage

##### Important Technical Elements

- WebSocket connections for live running updates
- Redis for real-time data and caching
- JWT authentication flow
- Domain event handling
- Error handling and exception flow

##### Additional Details

- Security filter chain
- Async operations
- Caching points
- Validation flow
- Error handling paths

##### Integration Points

- WebSocket connections
- Redis pub/sub
- External auth providers
- Database connections

Key Relationships to Emphasize:
- User authentication flow
- Live running session management
- Crew membership handling
- Record keeping and statistics

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        CL[Client Applications]
    end

    subgraph Gateway
        LB[Load Balancer/API Gateway]
    end

    subgraph "API Layer"
        AC["Auth Controller"]:::controller
        UC["User Controller"]:::controller
        CC["Crew Controller"]:::controller
        RC["Run Controller"]:::controller
        LRC["Live Running Controller"]:::controller
        RRC["Run Record Controller"]:::controller
        WSC["WebSocket Controller"]:::websocket
    end

    subgraph "Service Layer"
        UAS["User Auth Service"]:::service
        CS["Crew Service"]:::service
        RLS["Running Live Service"]:::service
        RCS["Record Command Service"]:::service
    end

    subgraph "Domain Layer"
        UD["User Domain"]:::domain
        CD["Crew Domain"]:::domain
        RD["Running Domain"]:::domain
    end

    subgraph "Persistence Layer"
        UR["User Repository"]:::repository
        CR["Crew Repository"]:::repository
        RR["Run Repository"]:::repository
        RER["Run Record Repository"]:::repository
        RC1["Redis Cache"]:::cache
        IMC["In-Memory Cache"]:::cache
    end

    CL --> LB
    LB --> AC & UC & CC & RC & LRC & RRC & WSC

    AC --> UAS
    UC --> UAS
    CC --> CS
    RC --> RLS
    LRC --> RLS
    RRC --> RCS
    WSC --> RLS

    UAS --> UD
    CS --> CD
    RLS --> RD
    RCS --> RD

    UD --> UR
    CD --> CR
    RD --> RR & RER
    RD --> RC1
    RD --> IMC

    %% Click events for component mapping
    click AC "https://github.com/Run-Us/Run-Us-server/blob/main/src/main/java/com/run_us/server/domains/user/controller/AuthController.java"
    click UAS "https://github.com/Run-Us/Run-Us-server/blob/main/src/main/java/com/run_us/server/domains/user/service/UserAuthService.java"
    click UR "https://github.com/Run-Us/Run-Us-server/blob/main/src/main/java/com/run_us/server/domains/user/repository/UserRepository.java"
    
    click CC "https://github.com/Run-Us/Run-Us-server/blob/main/src/main/java/com/run_us/server/domains/crew/controller/CrewController.java"
    click CS "https://github.com/Run-Us/Run-Us-server/blob/main/src/main/java/com/run_us/server/domains/crew/service/CrewService.java"
    click CR "https://github.com/Run-Us/Run-Us-server/blob/main/src/main/java/com/run_us/server/domains/crew/repository/CrewRepository.java"
    
    click LRC "https://github.com/Run-Us/Run-Us-server/blob/main/src/main/java/com/run_us/server/domains/running/live/controller/LiveRunningController.java"
    click WSC "https://github.com/Run-Us/Run-Us-server/blob/main/src/main/java/com/run_us/server/domains/running/live/controller/RunningSocketController.java"
    click RLS "https://github.com/Run-Us/Run-Us-server/blob/main/src/main/java/com/run_us/server/domains/running/live/service/RunningLiveService.java"
    click RR "https://github.com/Run-Us/Run-Us-server/blob/main/src/main/java/com/run_us/server/domains/running/run/repository/RunRepository.java"
    
    click RRC "https://github.com/Run-Us/Run-Us-server/blob/main/src/main/java/com/run_us/server/domains/running/record/controller/RunRecordController.java"
    click RCS "https://github.com/Run-Us/Run-Us-server/blob/main/src/main/java/com/run_us/server/domains/running/record/service/RecordCommandService.java"
    click RER "https://github.com/Run-Us/Run-Us-server/blob/main/src/main/java/com/run_us/server/domains/running/record/repository/RunRecordRepository.java"
    
    click RC1 "https://github.com/Run-Us/Run-Us-server/blob/main/src/main/java/com/run_us/server/global/config/RedisConfig.java"
    click IMC "https://github.com/Run-Us/Run-Us-server/blob/main/src/main/java/com/run_us/server/global/common/cache/InMemoryCache.java"
    click WSC "https://github.com/Run-Us/Run-Us-server/blob/main/src/main/java/com/run_us/server/global/config/WebSocketConfig.java"

    %% Styling
    classDef controller fill:#2196F3,stroke:#1565C0,color:white
    classDef service fill:#4CAF50,stroke:#2E7D32,color:white
    classDef domain fill:#FFC107,stroke:#FFA000,color:black
    classDef repository fill:#FF9800,stroke:#F57C00,color:white
    classDef cache fill:#E91E63,stroke:#C2185B,color:white
    classDef websocket fill:#9C27B0,stroke:#7B1FA2,color:white

    %% Legend
    subgraph Legend
        L1[Controller]:::controller
        L2[Service]:::service
        L3[Domain]:::domain
        L4[Repository]:::repository
        L5[Cache]:::cache
        L6[WebSocket]:::websocket
    end
```
