# sentrionic/valkyrie architecture

> Architecture diagram of the GitHub repository sentrionic/valkyrie, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sentrionic/valkyrie
- Repository: https://github.com/sentrionic/valkyrie

## Overview

##### Main Components

a. Client-Side (Web Application):
- React Frontend (Primary UI)
- State Management Layer (React Query & Zustand)
- WebSocket Clients (Multiple socket connections for different features)
- API Client Layer (Axios)

b. Server-Side:
- Gin HTTP Server
- WebSocket Hub/Rooms
- Service Layer
- Repository Layer
- Authentication Middleware

c. External Services:
- PostgreSQL Database
- Redis Cache
- AWS S3
- Gmail Service

##### Key Relationships to Highlight

a. Client-Server Communication:
- HTTP REST APIs (for CRUD operations)
- WebSocket connections (for real-time features)
- File upload pipeline to S3

b. Server-Database Interactions:
- GORM ORM layer between services and PostgreSQL
- Redis for session management and reset tokens
- S3 for file storage

- Frontend     | --> |    Backend    | --> |   Databases   |
- (React)      |     |    (Go)       |     | & External    |

##### Detailed Component Breakdown

Frontend Layer:

- React UI         |

- Components     | |

- State Stores   | |

- API Clients    | |

- WS Clients     | |

Backend Layer:

- Gin Server         |

- Handlers      |     |

- Services      |     |

- Repositories  |     |

- WebSocket Hub |     |

##### Important Flows to Illustrate

a. Authentication Flow:
**Client -> Auth Handler -> User Service -> Redis/PostgreSQL**

b. Real-time Communication:
**Client WS -> WS Hub -> Room -> Multiple Clients**

c. File Upload:
**Client -> Handler -> S3 -> Database Reference**

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Frontend
        UI["React UI Components"]:::frontend
        StateManagement["State Management (React Query & Zustand)"]:::frontend
        WSClients["WebSocket Clients"]:::frontend
        APIClient["API Client Layer"]:::frontend
        FrontendModels["Frontend Models/DTOs"]:::frontend
        FrontendRouting["Frontend Routing (/app/*, /channels/*, /login, /register)"]:::frontend
        FrontendValidation["Frontend Validation"]:::frontend
        APIInputDTOs["API Input DTOs"]:::frontend
    end

    subgraph Backend
        GinServer["Gin HTTP Server"]:::backend
        WSHub["WebSocket Hub"]:::backend
        ServiceLayer["Service Layer"]:::backend
        RepoLayer["Repository Layer"]:::backend
        AuthMiddleware["Authentication Middleware"]:::security
        APIRoutes["API Routes (/api/auth/*, /api/channels/*, /api/members/*, /api/messages/*)"]:::backend
        DataModels["Data Models"]:::backend
        WSActions["WebSocket Actions"]:::backend
    end

    subgraph ExternalServices
        PostgreSQL[(PostgreSQL)]:::database
        Redis[(Redis Cache)]:::database
        S3["AWS S3 (/api/files/*)"]:::external
        Gmail["Gmail Service (/api/auth/forgot-password/*)"]:::external
    end

    %% Frontend Relationships
    UI --> StateManagement
    UI --> WSClients
    UI --> APIClient
    StateManagement --> APIClient
    APIClient --> FrontendModels
    APIInputDTOs --> APIClient
    UI --> FrontendRouting
    UI --> FrontendValidation

    %% Backend Relationships
    GinServer --> AuthMiddleware
    AuthMiddleware --> APIRoutes
    APIRoutes --> ServiceLayer
    ServiceLayer --> RepoLayer
    WSHub --> WSActions
    WSActions --> ServiceLayer

    %% External Service Relationships
    RepoLayer --> PostgreSQL
    RepoLayer --> Redis
    RepoLayer --> S3
    RepoLayer --> Gmail

    %% Cross-Layer Communication
    APIClient --> GinServer
    WSClients --> WSHub

    %% Click Events
    click UI "https://github.com/sentrionic/Valkyrie/tree/main/web/src/components/"
    click StateManagement "https://github.com/sentrionic/Valkyrie/tree/main/web/src/lib/stores/"
    click WSClients "https://github.com/sentrionic/Valkyrie/tree/main/web/src/lib/api/ws/"
    click APIClient "https://github.com/sentrionic/Valkyrie/tree/main/web/src/lib/api/handler/"
    click GinServer "https://github.com/sentrionic/Valkyrie/blob/main/server/main.go"
    click WSHub "https://github.com/sentrionic/Valkyrie/tree/main/server/ws/"
    click ServiceLayer "https://github.com/sentrionic/Valkyrie/tree/main/server/service/"
    click RepoLayer "https://github.com/sentrionic/Valkyrie/tree/main/server/repository/"
    click AuthMiddleware "https://github.com/sentrionic/Valkyrie/tree/main/server/handler/middleware/"
    click Gmail "https://github.com/sentrionic/Valkyrie/blob/main/server/repository/mail_repository.go"
    click S3 "https://github.com/sentrionic/Valkyrie/blob/main/server/repository/file_repository.go"
    click Redis "https://github.com/sentrionic/Valkyrie/blob/main/server/repository/redis_repository.go"
    click APIRoutes "https://github.com/sentrionic/Valkyrie/tree/main/server/handler/"
    click DataModels "https://github.com/sentrionic/Valkyrie/tree/main/server/model/"
    click FrontendModels "https://github.com/sentrionic/Valkyrie/tree/main/web/src/lib/models/"
    click WSActions "https://github.com/sentrionic/Valkyrie/blob/main/server/ws/actions.go"
    click APIInputDTOs "https://github.com/sentrionic/Valkyrie/tree/main/web/src/lib/api/dtos/"
    click FrontendRouting "https://github.com/sentrionic/Valkyrie/tree/main/web/src/routes/"
    click FrontendValidation "https://github.com/sentrionic/Valkyrie/tree/main/web/src/lib/utils/validation/"

    classDef frontend fill:#2196F3,stroke:#1565C0,color:white
    classDef backend fill:#4CAF50,stroke:#2E7D32,color:white
    classDef database fill:#FFC107,stroke:#FFA000,color:black
    classDef external fill:#9C27B0,stroke:#7B1FA2,color:white
    classDef security fill:#F44336,stroke:#C62828,color:white

    %% Legend
    subgraph Legend
        Frontend_L[Frontend]:::frontend
        Backend_L[Backend]:::backend
        Database_L[Database]:::database
        External_L[External Service]:::external
        Security_L[Security]:::security
    end
```
