# mandarine-io/backend architecture

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

- Interactive diagram: https://gitdiagram.com/mandarine-io/backend
- Repository: https://github.com/mandarine-io/backend

## Overview

##### Main Components

a. Core Application Layer:
- HTTP Server (Gin Gonic)
- WebSocket Server
- Authentication System (JWT + OAuth2 providers)
- Service Layer
- Domain Layer
- Repository Layer

b. External Services:
- PostgreSQL with PostGIS
- Redis (for caching and pub/sub)
- MinIO (S3-compatible storage)
- SMTP Server
- Multiple Geocoding Providers
- OAuth2 Providers

**[Client Layer]**

**[Transport Layer]**

**[Service Layer]**

**[Persistence Layer]**

**[External Services]**

##### Component Details

a. Transport Layer (internal/transport):
- HTTP Handlers (/v0/*)
- WebSocket Handler
- Middleware Components
- Input Validators

b. Service Layer (internal/domain/service):
- Account Service
- Auth Service
- Geocoding Service
- Health Service
- Master Profile Service
- Resource Service
- WebSocket Service

c. Persistence Layer:
- GORM Repositories
- Cache Managers (Redis/Memory)
- File Storage (MinIO)

d. External Services Integration:
- Multiple Geocoding Providers (Graphhoper, Here, LocationIQ, etc.)
- OAuth Providers (Google, Yandex, Mail.ru)
- Email Service

##### Important Architectural Patterns to Highlight

- Clean Architecture pattern (visible in the layer separation)
- Repository Pattern (for data access)
- Factory Pattern (for geocoding and OAuth providers)
- Pub/Sub Pattern (using Redis)
- Middleware Chain Pattern (for HTTP handlers)

##### Additional Elements

- Background jobs (internal/job)
- Health check system
- Configuration management
- Caching strategy
- Security layer (JWT, middleware)
- Database migrations flow

##### Key Interactions to Highlight

- Authentication flow with multiple OAuth providers
- Geocoding service provider selection and failover
- WebSocket connection handling and pooling
- Cache layer interaction with database
- File storage operations with MinIO
- Health check system monitoring all components

## Diagram (Mermaid)

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

    subgraph Transport["Transport Layer"]
        HTTP["HTTP Server (Gin)"]:::transport
        WS["WebSocket Server"]:::transport
        MW["Middleware Chain"]:::transport
        VAL["Input Validators"]:::transport
    end

    subgraph Services["Service Layer"]
        AS["Account Service"]:::service
        AUS["Auth Service"]:::service
        GS["Geocoding Service"]:::service
        HS["Health Service"]:::service
        MPS["Master Profile Service"]:::service
        RS["Resource Service"]:::service
        WSS["WebSocket Service"]:::service
    end

    subgraph Persistence["Persistence Layer"]
        REPO["GORM Repositories"]:::persistence
        CACHE["Cache Manager"]:::persistence
        FILES["File Storage"]:::persistence
    end

    subgraph External["External Services"]
        DB[(PostgreSQL)]:::database
        REDIS[(Redis)]:::database
        MINIO[(MinIO)]:::storage
        SMTP[SMTP Server]:::external
        
        subgraph GeoProviders["Geocoding Providers"]
            GRAPH["Graphhoper"]:::external
            HERE["Here"]:::external
            LOC["LocationIQ"]:::external
            YAN["Yandex"]:::external
        end
        
        subgraph OAuth["OAuth Providers"]
            GOOGLE["Google"]:::external
            YAUTH["Yandex"]:::external
            MAIL["Mail.ru"]:::external
        end
    end

    subgraph System["System Components"]
        CONF["Configuration"]:::system
        HEALTH["Health Monitor"]:::system
        JOBS["Background Jobs"]:::system
    end

    %% Connections
    CL --> HTTP
    CL --> WS
    
    HTTP --> MW
    MW --> VAL
    
    HTTP --> AS & AUS & GS & HS & MPS & RS
    WS --> WSS
    
    AS & AUS & GS & HS & MPS & RS --> REPO
    WSS --> REPO
    
    REPO --> DB
    CACHE --> REDIS
    FILES --> MINIO
    
    AUS --> OAuth
    GS --> GeoProviders
    
    JOBS --> REPO
    HEALTH --> |Monitors| DB & REDIS & MINIO
    
    %% Styles
    classDef transport fill:#3498db
    classDef service fill:#2ecc71
    classDef persistence fill:#e74c3c
    classDef database fill:#f1c40f
    classDef external fill:#9b59b6
    classDef storage fill:#e67e22
    classDef system fill:#95a5a6

    %% Click Events
    click HTTP "https://github.com/mandarine-io/Backend/tree/main/internal/transport/http/"
    click WS "https://github.com/mandarine-io/Backend/tree/main/pkg/websocket/"
    click AS "https://github.com/mandarine-io/Backend/tree/main/internal/domain/service/account/"
    click AUS "https://github.com/mandarine-io/Backend/tree/main/internal/domain/service/auth/"
    click GS "https://github.com/mandarine-io/Backend/tree/main/internal/domain/service/geocoding/"
    click HS "https://github.com/mandarine-io/Backend/tree/main/internal/domain/service/health/"
    click MPS "https://github.com/mandarine-io/Backend/tree/main/internal/domain/service/master/"
    click RS "https://github.com/mandarine-io/Backend/tree/main/internal/domain/service/resource/"
    click WSS "https://github.com/mandarine-io/Backend/tree/main/internal/domain/service/ws/"
    click REPO "https://github.com/mandarine-io/Backend/tree/main/internal/persistence/repo/"
    click CACHE "https://github.com/mandarine-io/Backend/tree/main/pkg/storage/cache/"
    click FILES "https://github.com/mandarine-io/Backend/tree/main/pkg/storage/s3/"
    click JOBS "https://github.com/mandarine-io/Backend/tree/main/internal/job/"
    click CONF "https://github.com/mandarine-io/Backend/tree/main/internal/config/"
    click HEALTH "https://github.com/mandarine-io/Backend/tree/main/internal/domain/service/health/check/"
    click GRAPH "https://github.com/mandarine-io/Backend/tree/main/pkg/geocoding/graphhoper/"
    click HERE "https://github.com/mandarine-io/Backend/tree/main/pkg/geocoding/here/"
    click LOC "https://github.com/mandarine-io/Backend/tree/main/pkg/geocoding/locationiq/"
    click YAN "https://github.com/mandarine-io/Backend/tree/main/pkg/geocoding/yandex/"
```
