# smthdev/winforce_platform_backend architecture

> Architecture diagram of the GitHub repository smthdev/winforce_platform_backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/smthdev/winforce_platform_backend
- Repository: https://github.com/smthdev/winforce_platform_backend

## Overview

Winforce is a Go API for account access, profiles, QR codes, balances, receipt processing, games, and Telegram linking. Users and administrators enter through the versioned HTTP API; authentication and admin middleware guard operations, which handlers delegate to domain services. Receipt uploads are parsed, stored, and recorded as balance activity. The route excerpt confirms several service/repository integrations, but source for many handlers and services was not sampled, so those internal links are omitted where their calls cannot be verified.

Main entry points: [`internal/routes/server.go`](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/routes/server.go) (API Router), [`internal/service/balance_service.go`](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/balance_service.go) (Balance Service), [`internal/middleware/auth.go`](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/middleware/auth.go) (Auth Middleware), [`internal/service/telegram_service.go`](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/telegram_service.go) (Telegram Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_router["API Router<br/>[server.go]"]
  node_authmw["Auth Middleware<br/>[auth.go]"]
end

subgraph group_identity["Identity and Profiles"]
  node_authhandler["Login Handler<br/>[auth_handler.go]"]
  node_authservice["Auth Setup<br/>[auth_service.go]"]
  node_profile["Profile Handlers<br/>[profile_handler.go]"]
  node_users["User Handlers<br/>[users_handler.go]"]
  node_profile_svc["Profile Service<br/>[profile_service.go]"]
  node_user_repo["User Repository<br/>[user_repo.go]"]
  node_avatar_handler["Avatar Handler<br/>[avatar_handler.go]"]
  node_avatar_svc["Avatar Service<br/>[avatar_service.go]"]
  node_avatar_repo["Avatar Repository<br/>[avatar_repo.go]"]
end

subgraph group_finance["Balance and Games"]
  node_balance_handler["Balance Handler<br/>[balance_handler.go]"]
  node_balance_svc["Balance Service<br/>[balance_service.go]"]
  node_balance_repo["Balance Repository<br/>[balance_repo.go]"]
  node_game_handler["Game Handler<br/>[game_handler.go]"]
  node_game_svc["Game Service<br/>[game_service.go]"]
  node_game_repo["Game Repository<br/>[game_repo.go]"]
end

subgraph group_integrations["Files and Integrations"]
  node_telegram_handler["Telegram Handler"]
  node_telegram_svc["Telegram Service"]
  node_telegram_repo["Telegram Repository<br/>[telegram_repo.go]"]
  node_qr_handler["QR Handler<br/>[qr_handler.go]"]
  node_qr_svc["QR Service<br/>[qr_service.go]"]
  node_qr_repo["QR Repository<br/>[qr_repo.go]"]
  node_file_handler["File Handler<br/>[file_handler.go]"]
  node_file_svc["File Service<br/>[file_service.go]"]
end

node_user(("User"))
node_admin(("Administrator"))
node_postgres[("PostgreSQL")]
node_object_store[("MinIO Storage")]
node_parser["Receipt Parser<br/>[parsing.go]"]
node_telegram_bot["Telegram Bot<br/>[bot.go]"]
node_auth_engine["Limen Auth"]

node_user -->|"sends requests"| node_router
node_admin -->|"sends requests"| node_router
node_router -->|"dispatches login"| node_authhandler
node_router -->|"dispatches auth"| node_auth_engine
node_router -->|"guards routes"| node_authmw
node_authhandler -->|"forwards sign-in"| node_auth_engine
node_authmw -->|"validates session"| node_auth_engine
node_authmw -->|"checks admin"| node_user_repo
node_router -->|"dispatches profile"| node_profile
node_router -->|"dispatches users"| node_users
node_profile -->|"calls"| node_profile_svc
node_users -->|"calls"| node_profile_svc
node_profile_svc -->|"reads and writes"| node_user_repo
node_router -->|"dispatches avatar"| node_avatar_handler
node_avatar_handler -->|"calls"| node_avatar_svc
node_router -->|"dispatches Telegram"| node_telegram_handler
node_telegram_handler -->|"calls"| node_telegram_svc
node_telegram_svc -->|"reads and writes"| node_telegram_repo
node_router -->|"dispatches QR"| node_qr_handler
node_qr_handler -->|"calls"| node_qr_svc
node_router -->|"dispatches files"| node_file_handler
node_file_handler -->|"calls"| node_file_svc
node_router -->|"dispatches balance"| node_balance_handler
node_balance_handler -->|"calls"| node_balance_svc
node_balance_svc -->|"reads and writes"| node_balance_repo
node_balance_svc -->|"parses receipt"| node_parser
node_balance_svc -->|"stores receipt"| node_object_store
node_router -->|"dispatches games"| node_game_handler
node_game_handler -->|"calls"| node_game_svc
node_auth_engine -->|"stores auth data"| node_postgres
node_user_repo -->|"queries"| node_postgres
node_avatar_repo -->|"queries"| node_postgres
node_telegram_repo -->|"queries"| node_postgres
node_qr_repo -->|"queries"| node_postgres
node_balance_repo -->|"queries"| node_postgres
node_game_repo -->|"queries"| node_postgres
node_avatar_svc -->|"stores avatars"| node_object_store
node_qr_svc -->|"stores QR files"| node_object_store
node_file_svc -->|"serves files"| node_object_store
node_telegram_svc -.->|"uses bot token"| node_telegram_bot

click node_router "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/routes/server.go"
click node_authmw "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/middleware/auth.go"
click node_authhandler "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/auth_handler.go"
click node_authservice "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/auth_service.go"
click node_profile "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/profile_handler.go"
click node_users "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/users_handler.go"
click node_profile_svc "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/profile_service.go"
click node_user_repo "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/repository/postgres/user_repo/user_repo.go"
click node_avatar_handler "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/avatar_handler.go"
click node_avatar_svc "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/avatar_service.go"
click node_avatar_repo "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/repository/postgres/avatar_repo/avatar_repo.go"
click node_telegram_handler "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/telegram_handler.go"
click node_telegram_svc "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/telegram_service.go"
click node_telegram_repo "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/repository/postgres/telegram_repo/telegram_repo.go"
click node_qr_handler "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/qr_handler.go"
click node_qr_svc "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/qr_service.go"
click node_qr_repo "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/repository/postgres/qr_repo/qr_repo.go"
click node_file_handler "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/file_handler.go"
click node_file_svc "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/file_service.go"
click node_balance_handler "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/balance_handler.go"
click node_balance_svc "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/balance_service.go"
click node_balance_repo "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/repository/postgres/balance_repo/balance_repo.go"
click node_game_handler "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/game_handler.go"
click node_game_svc "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/game_service.go"
click node_game_repo "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/repository/postgres/game_repo/game_repo.go"
click node_parser "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/repository/parsing/parsing.go"
click node_telegram_bot "https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/repository/telegram/bot.go"

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_router,node_authmw,node_user toneBlue
class node_authhandler,node_authservice,node_profile,node_users,node_profile_svc,node_user_repo,node_avatar_handler,node_avatar_svc,node_avatar_repo,node_postgres,node_object_store toneAmber
class node_balance_handler,node_balance_svc,node_balance_repo,node_game_handler,node_game_svc,node_game_repo toneMint
class node_telegram_handler,node_telegram_svc,node_telegram_repo,node_qr_handler,node_qr_svc,node_qr_repo,node_file_handler,node_file_svc toneRose
class node_admin,node_auth_engine toneIndigo
class node_parser,node_telegram_bot toneTeal
```

## Components

### HTTP API

- [API Router](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/routes/server.go): `internal/routes/server.go`
- [Auth Middleware](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/middleware/auth.go): `internal/middleware/auth.go`

### Identity and Profiles

- [Login Handler](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/auth_handler.go): `internal/handlers/auth_handler.go`
- [Auth Setup](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/auth_service.go): `internal/service/auth_service.go`
- [Profile Handlers](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/profile_handler.go): `internal/handlers/profile_handler.go`
- [User Handlers](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/users_handler.go): `internal/handlers/users_handler.go`
- [Profile Service](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/profile_service.go): `internal/service/profile_service.go`
- [User Repository](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/repository/postgres/user_repo/user_repo.go): `internal/repository/postgres/user_repo/user_repo.go`
- [Avatar Handler](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/avatar_handler.go): `internal/handlers/avatar_handler.go`
- [Avatar Service](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/avatar_service.go): `internal/service/avatar_service.go`
- [Avatar Repository](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/repository/postgres/avatar_repo/avatar_repo.go): `internal/repository/postgres/avatar_repo/avatar_repo.go`

### Balance and Games

- [Balance Handler](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/balance_handler.go): `internal/handlers/balance_handler.go`
- [Balance Service](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/balance_service.go): `internal/service/balance_service.go`
- [Balance Repository](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/repository/postgres/balance_repo/balance_repo.go): `internal/repository/postgres/balance_repo/balance_repo.go`
- [Game Handler](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/game_handler.go): `internal/handlers/game_handler.go`
- [Game Service](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/game_service.go): `internal/service/game_service.go`
- [Game Repository](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/repository/postgres/game_repo/game_repo.go): `internal/repository/postgres/game_repo/game_repo.go`

### Files and Integrations

- [Telegram Handler](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/telegram_handler.go): `internal/handlers/telegram_handler.go`
- [Telegram Service](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/telegram_service.go): `internal/service/telegram_service.go`
- [Telegram Repository](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/repository/postgres/telegram_repo/telegram_repo.go): `internal/repository/postgres/telegram_repo/telegram_repo.go`
- [QR Handler](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/qr_handler.go): `internal/handlers/qr_handler.go`
- [QR Service](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/qr_service.go): `internal/service/qr_service.go`
- [QR Repository](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/repository/postgres/qr_repo/qr_repo.go): `internal/repository/postgres/qr_repo/qr_repo.go`
- [File Handler](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/handlers/file_handler.go): `internal/handlers/file_handler.go`
- [File Service](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/service/file_service.go): `internal/service/file_service.go`

### Other components

- **User**
- **Administrator**
- **PostgreSQL**
- **MinIO Storage**
- [Receipt Parser](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/repository/parsing/parsing.go): `internal/repository/parsing/parsing.go`
- [Telegram Bot](https://github.com/smthdev/winforce_platform_backend/blob/dev/internal/repository/telegram/bot.go): `internal/repository/telegram/bot.go`
- **Limen Auth**

## Connections

- User → API Router: sends requests
- Administrator → API Router: sends requests
- API Router → Login Handler: dispatches login
- API Router → Limen Auth: dispatches auth
- API Router → Auth Middleware: guards routes
- Login Handler → Limen Auth: forwards sign-in
- Auth Middleware → Limen Auth: validates session
- Auth Middleware → User Repository: checks admin
- API Router → Profile Handlers: dispatches profile
- API Router → User Handlers: dispatches users
- Profile Handlers → Profile Service: calls
- User Handlers → Profile Service: calls
- Profile Service → User Repository: reads and writes
- API Router → Avatar Handler: dispatches avatar
- Avatar Handler → Avatar Service: calls
- API Router → Telegram Handler: dispatches Telegram
- Telegram Handler → Telegram Service: calls
- Telegram Service → Telegram Repository: reads and writes
- API Router → QR Handler: dispatches QR
- QR Handler → QR Service: calls
- API Router → File Handler: dispatches files
- File Handler → File Service: calls
- API Router → Balance Handler: dispatches balance
- Balance Handler → Balance Service: calls
- Balance Service → Balance Repository: reads and writes
- Balance Service → Receipt Parser: parses receipt
- Balance Service → MinIO Storage: stores receipt
- API Router → Game Handler: dispatches games
- Game Handler → Game Service: calls
- Limen Auth → PostgreSQL: stores auth data
- User Repository → PostgreSQL: queries
- Avatar Repository → PostgreSQL: queries
- Telegram Repository → PostgreSQL: queries
- QR Repository → PostgreSQL: queries
- Balance Repository → PostgreSQL: queries
- Game Repository → PostgreSQL: queries
- Avatar Service → MinIO Storage: stores avatars
- QR Service → MinIO Storage: stores QR files
- File Service → MinIO Storage: serves files
- Telegram Service → Telegram Bot: uses bot token