# brankonymous/glense architecture

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

- Interactive diagram: https://gitdiagram.com/brankonymous/glense
- Repository: https://github.com/brankonymous/glense

## Overview

1. **Overall shape**
   Glense is a microservice system with a React/Vite frontend, a YARP API gateway, four .NET 8 backend services, separate PostgreSQL databases per service, and RabbitMQ for async events. The repo also contains Kubernetes manifests, Dockerfiles, and integration-test projects, so deployment and test boundaries are explicit.

2. **Edge layer**
   The browser app in `glense.client/` is the main user entrypoint. It talks to the system through the gateway rather than directly to services. Frontend code is organized around feature components plus a thin API/service layer, which keeps UI state and backend integration separated.

3. **API gateway boundary**
   The gateway routes public traffic by path:
   - auth/profile → Account service
   - videos/search/playlists/comments/subscriptions → Video Catalogue
   - donations/wallets → Donation
   - chats/messages → Chat
   - `/hubs/chat` → Chat SignalR hub  
   It also centralizes CORS and health endpoints, so the browser only needs one base URL.

4. **Account service**
   `services/Glense.AccountService` owns identity and user-facing account data. It handles registration, login/JWT issuance, profiles, notifications, and an internal API for service-to-service requests. It also exposes a gRPC service for username/profile lookup and consumes RabbitMQ events to create notifications. Its persistence is isolated in its own PostgreSQL database.

5. **Video Catalogue service**
   `services/Glense.VideoCatalogue` owns videos, uploads, comments, playlists, likes, and subscriptions. It uses EF Core over its own PostgreSQL DB and has a storage abstraction for uploaded video files, with a local-file implementation in the repo. This service also depends on Account over gRPC to resolve usernames and uses RabbitMQ to notify Account about subscription-related events.

6. **Donation service**
   `Glense.Server/DonationService` owns wallets and donation transfers. It validates recipients through Account’s internal HTTP API, then performs balance changes in its own database. It publishes donation events asynchronously so Account can generate notifications, and it consumes user-registration events to provision wallets for new users.

7. **Chat service**
   `services/Glense.ChatService` owns chat rooms and messages. It exposes REST controllers for chat/message management and a SignalR hub for real-time messaging. Like the other services, it has a dedicated PostgreSQL database and is deployed independently.

8. **Async event bus**
   RabbitMQ is the main decoupling mechanism between services. The important event flows are:
   - Account registration → Donation creates a wallet
   - Donation made → Account creates a notification
   - User subscribed → Account creates a notification  
   This keeps user-facing requests from blocking on downstream work.

9. **Synchronous internal calls**
   Not everything is event-driven. Donation performs a synchronous validation call into Account before transferring funds, and Video Catalogue uses gRPC to resolve user data efficiently. Both internal HTTP and gRPC traffic are protected with a shared `INTERNAL_API_KEY`, which marks them as trusted service-to-service boundaries.

10. **Data ownership**
   Each service owns its schema and DbContext, and the Kubernetes manifests mirror that ownership with separate Postgres deployments, services, and persistent volumes. This makes the architecture strongly bounded: no shared application database, and cross-service reads happen through APIs or events rather than direct DB access.

11. **Runtime, deployment, and test seams**
   The repo supports local Docker Compose development and Kubernetes deployment. Integration tests are split by service and use `WebApplicationFactory` with in-memory databases and mocked external dependencies, which reinforces the service boundaries without requiring a full cluster to test behavior.

Main entry points: [`k8s`](https://github.com/brankonymous/glense/tree/main/k8s) (Kubernetes), [`services/Glense.AccountService`](https://github.com/brankonymous/glense/blob/main/services/Glense.AccountService) (Account API), [`Glense.Server`](https://github.com/brankonymous/glense/blob/main/Glense.Server) (Gateway), [`services/Glense.VideoCatalogue`](https://github.com/brankonymous/glense/blob/main/services/Glense.VideoCatalogue) (Video catalogue)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_client["Frontend"]
  node_node_client_app["Client app<br/>react/vite UI<br/>[src]"]
  node_node_client_api["API layer<br/>frontend service layer<br/>[services]"]
end

subgraph group_grp_gateway["Edge Gateway"]
  node_node_gateway["Gateway<br/>YARP proxy<br/>[Glense.Server]"]
end

subgraph group_grp_services["Backend Services"]
  node_node_account_api["Account API<br/>identity service"]
  node_node_account_grpc(("Account gRPC<br/>lookup RPC"))
  node_node_video_api["Video catalogue<br/>media service"]
  node_node_video_storage["Video storage<br/>file abstraction"]
  node_node_donation_api["Donation service<br/>wallet service<br/>[DonationService]"]
  node_node_chat_api["Chat service<br/>messaging service<br/>[Glense.ChatService]"]
  node_node_chat_hub(("Chat hub<br/>signalR hub<br/>[ChatHub.cs]"))
end

subgraph group_grp_data["Datastores"]
  node_node_rabbitmq["RabbitMQ<br/>event bus"]
  node_node_account_db[("Account DB<br/>postgres schema<br/>[schema.sql]")]
  node_node_video_db[("Video DB<br/>postgres schema<br/>[schema.sql]")]
  node_node_donation_db[("Donation DB<br/>postgres schema<br/>[schema.sql]")]
  node_node_chat_db[("Chat DB<br/>postgres schema<br/>[schema.sql]")]
  node_node_k8s["Kubernetes<br/>deploy manifests"]
end

subgraph group_grp_tests["Integration Tests"]
  node_node_acc_tests["Account tests<br/>integration suite"]
  node_node_video_tests["Video tests<br/>integration suite"]
  node_node_donation_tests["Donation tests<br/>integration suite"]
  node_node_chat_tests["Chat tests<br/>integration suite"]
end

node_node_client_app -->|"uses"| node_node_client_api
node_node_client_api -->|"public API"| node_node_gateway
node_node_gateway -->|"auth/profile"| node_node_account_api
node_node_gateway -->|"video/search"| node_node_video_api
node_node_gateway -->|"donations/wallets"| node_node_donation_api
node_node_gateway -->|"chats/messages"| node_node_chat_api
node_node_gateway -->|"/hubs/chat"| node_node_chat_hub
node_node_account_api -->|"serves"| node_node_account_grpc
node_node_account_api -->|"persists"| node_node_account_db
node_node_account_api -->|"publishes/consumes"| node_node_rabbitmq
node_node_video_api -->|"persists"| node_node_video_db
node_node_video_api -->|"stores media"| node_node_video_storage
node_node_video_api -->|"resolves users"| node_node_account_grpc
node_node_video_api -->|"publishes"| node_node_rabbitmq
node_node_donation_api -->|"validates recipients"| node_node_account_api
node_node_donation_api -->|"persists"| node_node_donation_db
node_node_donation_api -->|"publishes/consumes"| node_node_rabbitmq
node_node_chat_api -->|"persists"| node_node_chat_db
node_node_account_api -.->|"notifies"| node_node_chat_api
node_node_k8s -->|"deploys"| node_node_gateway
node_node_k8s -->|"deploys"| node_node_account_api
node_node_k8s -->|"deploys"| node_node_video_api
node_node_k8s -->|"deploys"| node_node_donation_api
node_node_k8s -->|"deploys"| node_node_chat_api
node_node_k8s -->|"deploys"| node_node_rabbitmq
node_node_k8s -->|"deploys"| node_node_account_db
node_node_k8s -->|"deploys"| node_node_video_db
node_node_k8s -->|"deploys"| node_node_donation_db
node_node_k8s -->|"deploys"| node_node_chat_db
node_node_acc_tests -.->|"covers"| node_node_account_api
node_node_video_tests -.->|"covers"| node_node_video_api
node_node_donation_tests -.->|"covers"| node_node_donation_api
node_node_chat_tests -.->|"covers"| node_node_chat_api

click node_node_client_app "https://github.com/brankonymous/glense/blob/main/glense.client/src"
click node_node_client_api "https://github.com/brankonymous/glense/blob/main/glense.client/src/services"
click node_node_gateway "https://github.com/brankonymous/glense/blob/main/Glense.Server"
click node_node_account_api "https://github.com/brankonymous/glense/blob/main/services/Glense.AccountService"
click node_node_account_grpc "https://github.com/brankonymous/glense/blob/main/services/Glense.AccountService/GrpcServices/AccountGrpcService.cs"
click node_node_video_api "https://github.com/brankonymous/glense/blob/main/services/Glense.VideoCatalogue"
click node_node_video_storage "https://github.com/brankonymous/glense/blob/main/services/Glense.VideoCatalogue/Services/LocalFileVideoStorage.cs"
click node_node_donation_api "https://github.com/brankonymous/glense/blob/main/Glense.Server/DonationService"
click node_node_chat_api "https://github.com/brankonymous/glense/blob/main/services/Glense.ChatService"
click node_node_chat_hub "https://github.com/brankonymous/glense/blob/main/services/Glense.ChatService/Hubs/ChatHub.cs"
click node_node_rabbitmq "https://github.com/brankonymous/glense/blob/main/k8s/rabbitmq-deployment.yaml"
click node_node_account_db "https://github.com/brankonymous/glense/blob/main/services/Glense.AccountService/database/schema.sql"
click node_node_video_db "https://github.com/brankonymous/glense/blob/main/services/Glense.VideoCatalogue/Database/schema.sql"
click node_node_donation_db "https://github.com/brankonymous/glense/blob/main/Glense.Server/DonationService/Data/schema.sql"
click node_node_chat_db "https://github.com/brankonymous/glense/blob/main/services/Glense.ChatService/database/schema.sql"
click node_node_k8s "https://github.com/brankonymous/glense/tree/main/k8s"
click node_node_acc_tests "https://github.com/brankonymous/glense/blob/main/tests/AccountService.IntegrationTests"
click node_node_video_tests "https://github.com/brankonymous/glense/blob/main/tests/VideoCatalogue.IntegrationTests"
click node_node_donation_tests "https://github.com/brankonymous/glense/blob/main/tests/DonationService.IntegrationTests"
click node_node_chat_tests "https://github.com/brankonymous/glense/blob/main/tests/ChatService.IntegrationTests"

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_node_client_app,node_node_client_api toneBlue
class node_node_gateway toneAmber
class node_node_account_api,node_node_account_grpc,node_node_video_api,node_node_video_storage,node_node_donation_api,node_node_chat_api,node_node_chat_hub toneMint
class node_node_rabbitmq,node_node_account_db,node_node_video_db,node_node_donation_db,node_node_chat_db,node_node_k8s toneRose
class node_node_acc_tests,node_node_video_tests,node_node_donation_tests,node_node_chat_tests toneIndigo
```

## Components

### Frontend

React/Vite browser app and its API-facing modules.

- [Client app](https://github.com/brankonymous/glense/blob/main/glense.client/src): react/vite UI · Browser entrypoint and feature composition for end users. · `glense.client/src`
- [API layer](https://github.com/brankonymous/glense/blob/main/glense.client/src/services): frontend service layer · Shared API clients and auth/profile/video/chat wrappers. · `glense.client/src/services`

### Edge Gateway

Public API routing and cross-cutting request boundary.

- [Gateway](https://github.com/brankonymous/glense/blob/main/Glense.Server): YARP proxy · Single public edge that routes requests to backend services and hubs. · `Glense.Server`

### Backend Services

Independent .NET services owning distinct business domains.

- [Account API](https://github.com/brankonymous/glense/blob/main/services/Glense.AccountService): identity service · Auth, profiles, notifications, and internal account lookups. · `services/Glense.AccountService`
- [Account gRPC](https://github.com/brankonymous/glense/blob/main/services/Glense.AccountService/GrpcServices/AccountGrpcService.cs): lookup RPC · Username/profile lookup contract used by other services. · `services/Glense.AccountService/GrpcServices/AccountGrpcService.cs`
- [Video catalogue](https://github.com/brankonymous/glense/blob/main/services/Glense.VideoCatalogue): media service · Videos, uploads, comments, playlists, likes, and subscriptions. · `services/Glense.VideoCatalogue`
- [Video storage](https://github.com/brankonymous/glense/blob/main/services/Glense.VideoCatalogue/Services/LocalFileVideoStorage.cs): file abstraction · Uploaded video persistence with local-file implementation in repo. · `services/Glense.VideoCatalogue/Services/LocalFileVideoStorage.cs`
- [Donation service](https://github.com/brankonymous/glense/blob/main/Glense.Server/DonationService): wallet service · Wallets, deposits, withdrawals, and donation transfers. · `Glense.Server/DonationService`
- [Chat service](https://github.com/brankonymous/glense/blob/main/services/Glense.ChatService): messaging service · Chat rooms, messages, and real-time messaging endpoints. · `services/Glense.ChatService`
- [Chat hub](https://github.com/brankonymous/glense/blob/main/services/Glense.ChatService/Hubs/ChatHub.cs): signalR hub · Real-time chat channel exposed alongside REST controllers. · `services/Glense.ChatService/Hubs/ChatHub.cs`

### Datastores

Per-service persistence and shared infrastructure.

- [RabbitMQ](https://github.com/brankonymous/glense/blob/main/k8s/rabbitmq-deployment.yaml): event bus · Async event backbone connecting account, donation, and video workflows. · `k8s/rabbitmq-deployment.yaml`
- [Account DB](https://github.com/brankonymous/glense/blob/main/services/Glense.AccountService/database/schema.sql): postgres schema · Dedicated PostgreSQL database for account and notification data. · `services/Glense.AccountService/database/schema.sql`
- [Video DB](https://github.com/brankonymous/glense/blob/main/services/Glense.VideoCatalogue/Database/schema.sql): postgres schema · Dedicated PostgreSQL database for catalogue data. · `services/Glense.VideoCatalogue/Database/schema.sql`
- [Donation DB](https://github.com/brankonymous/glense/blob/main/Glense.Server/DonationService/Data/schema.sql): postgres schema · Dedicated PostgreSQL database for wallet and donation state. · `Glense.Server/DonationService/Data/schema.sql`
- [Chat DB](https://github.com/brankonymous/glense/blob/main/services/Glense.ChatService/database/schema.sql): postgres schema · Dedicated PostgreSQL database for chat state. · `services/Glense.ChatService/database/schema.sql`
- [Kubernetes](https://github.com/brankonymous/glense/tree/main/k8s): deploy manifests · Service, Postgres, and RabbitMQ deployment manifests. · `k8s`

### Integration Tests

Service-level integration suites and shared test helpers.

- [Account tests](https://github.com/brankonymous/glense/blob/main/tests/AccountService.IntegrationTests): integration suite · HTTP and consumer integration coverage for the account service. · `tests/AccountService.IntegrationTests`
- [Video tests](https://github.com/brankonymous/glense/blob/main/tests/VideoCatalogue.IntegrationTests): integration suite · Controller and storage-adjacent integration coverage for catalogue flows. · `tests/VideoCatalogue.IntegrationTests`
- [Donation tests](https://github.com/brankonymous/glense/blob/main/tests/DonationService.IntegrationTests): integration suite · Controller, DB, and consumer integration coverage for donation flows. · `tests/DonationService.IntegrationTests`
- [Chat tests](https://github.com/brankonymous/glense/blob/main/tests/ChatService.IntegrationTests): integration suite · Controller integration coverage for chat and message flows. · `tests/ChatService.IntegrationTests`

## Connections

- Client app → API layer: uses · UI calls shared frontend API wrappers.
- API layer → Gateway: public API · Browser traffic goes through the gateway base URL.
- Gateway → Account API: auth/profile · Routes identity and profile traffic to account.
- Gateway → Video catalogue: video/search · Routes content browsing and playback traffic to catalogue.
- Gateway → Donation service: donations/wallets · Routes wallet and donation traffic to donation.
- Gateway → Chat service: chats/messages · Routes chat traffic to the chat service.
- Gateway → Chat hub: /hubs/chat · Exposes the real-time chat hub through the edge.
- Account API → Account gRPC: serves · Provides trusted profile lookup RPC.
- Account API → Account DB: persists · Owns identity and notification state.
- Account API → RabbitMQ: publishes/consumes · Handles registration, donation, and subscription events.
- Video catalogue → Video DB: persists · Owns catalogue and interaction state.
- Video catalogue → Video storage: stores media · Uploads are written through the storage abstraction.
- Video catalogue → Account gRPC: resolves users · Uses account lookup RPC for usernames/profile data.
- Video catalogue → RabbitMQ: publishes · Emits subscription-related events for notifications.
- Donation service → Account API: validates recipients · Uses trusted internal HTTP before transfers.
- Donation service → Donation DB: persists · Owns wallets and donation transactions.
- Donation service → RabbitMQ: publishes/consumes · Consumes registration and publishes donation events.
- Chat service → Chat DB: persists · Owns chats and message history.
- Account API → Chat service: notifies · Account notifications reflect chat-related activity indirectly via events.
- Kubernetes → Gateway: deploys · Kubernetes manifests deploy the edge gateway.
- Kubernetes → Account API: deploys · Kubernetes manifests deploy the account service.
- Kubernetes → Video catalogue: deploys · Kubernetes manifests deploy the video catalogue service.
- Kubernetes → Donation service: deploys · Kubernetes manifests deploy the donation service.
- Kubernetes → Chat service: deploys · Kubernetes manifests deploy the chat service.
- Kubernetes → RabbitMQ: deploys · Kubernetes manifests deploy the event bus.
- Kubernetes → Account DB: deploys · Kubernetes manifests deploy service-owned Postgres.
- Kubernetes → Video DB: deploys · Kubernetes manifests deploy service-owned Postgres.
- Kubernetes → Donation DB: deploys · Kubernetes manifests deploy service-owned Postgres.
- Kubernetes → Chat DB: deploys · Kubernetes manifests deploy service-owned Postgres.
- Account tests → Account API: covers · Service-specific integration suite.
- Video tests → Video catalogue: covers · Service-specific integration suite.
- Donation tests → Donation service: covers · Service-specific integration suite.
- Chat tests → Chat service: covers · Service-specific integration suite.
