# zvash/bgmood-api-gateway architecture

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

- Interactive diagram: https://gitdiagram.com/zvash/bgmood-api-gateway
- Repository: https://github.com/zvash/bgmood-api-gateway

## Overview

bgmood-api-gateway is a gRPC gateway for authentication, circle management, and mood-sharing operations. Clients call the registered gRPC API; handlers in `internal/gapi` forward supported operations to downstream auth and circle services, adapting request context and streaming API calls. The tree documents additional session, email-verification, circle-membership, reaction, and file-upload capabilities. Source excerpts show auth forwarding and server registration; detailed wiring for other handlers and the file client was not sampled, so those links are omitted where uncertain.

Main entry points: [`main.go`](https://github.com/zvash/bgmood-api-gateway/blob/main/main.go) (gRPC server), [`internal/gapi`](https://github.com/zvash/bgmood-api-gateway/tree/main/internal/gapi) (API handlers), [`internal/gapi/rpc_auth_service_methods.go`](https://github.com/zvash/bgmood-api-gateway/blob/main/internal/gapi/rpc_auth_service_methods.go) (Auth handlers), [`internal/client/auth_service_client.go`](https://github.com/zvash/bgmood-api-gateway/blob/main/internal/client/auth_service_client.go) (Auth client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Gateway API"]
  node_server["gRPC server<br/>[main.go]"]
  node_handlers["API handlers"]
  node_api_contract["App API contract"]
end

subgraph group_identity["Identity"]
  node_auth_handlers["Auth handlers"]
  node_auth_context["Request context<br/>[client_context.go]"]
  node_auth_client["Auth client"]
  node_auth_contract["Auth RPC contract"]
end

subgraph group_circles["Circles and mood"]
  node_circle_handlers["Circle and mood handlers"]
  node_circle_client["Circle client"]
  node_circle_contract["Circles RPC contract"]
  node_file_client["File client"]
  node_file_contract["File RPC contract"]
end

subgraph group_runtime["Runtime and telemetry"]
  node_metrics["Server metrics<br/>[server_metrics.go]"]
  node_metrics_endpoint["Metrics endpoint<br/>[main.go]"]
  node_config["Runtime config<br/>[config.go]"]
end

node_caller(("gRPC client"))
node_auth_service{{"Auth service"}}
node_circle_service{{"Circles service"}}

node_caller -->|"calls gRPC"| node_server
node_server -->|"registers API"| node_api_contract
node_server -->|"serves requests"| node_handlers
node_server -->|"instruments RPCs"| node_metrics
node_server -->|"starts endpoint"| node_metrics_endpoint
node_server -->|"loads config"| node_config
node_handlers -->|"dispatches auth"| node_auth_handlers
node_auth_handlers -->|"builds context"| node_auth_context
node_auth_handlers -->|"forwards auth RPCs"| node_auth_client
node_auth_client -->|"invokes RPCs"| node_auth_contract
node_auth_contract -->|"sends RPCs"| node_auth_service
node_handlers -->|"dispatches app RPCs"| node_circle_handlers
node_circle_handlers -->|"forwards circle RPCs"| node_circle_client
node_circle_client -->|"invokes RPCs"| node_circle_contract
node_circle_contract -->|"sends RPCs"| node_circle_service
node_metrics_endpoint -->|"exposes metrics"| node_caller

click node_server "https://github.com/zvash/bgmood-api-gateway/blob/main/main.go"
click node_handlers "https://github.com/zvash/bgmood-api-gateway/tree/main/internal/gapi"
click node_api_contract "https://github.com/zvash/bgmood-api-gateway/blob/main/internal/pb/api_service_grpc.pb.go"
click node_auth_handlers "https://github.com/zvash/bgmood-api-gateway/blob/main/internal/gapi/rpc_auth_service_methods.go"
click node_auth_context "https://github.com/zvash/bgmood-api-gateway/blob/main/internal/gapi/client_context.go"
click node_auth_client "https://github.com/zvash/bgmood-api-gateway/blob/main/internal/client/auth_service_client.go"
click node_auth_contract "https://github.com/zvash/bgmood-api-gateway/blob/main/internal/authpb/service_auth_grpc.pb.go"
click node_circle_handlers "https://github.com/zvash/bgmood-api-gateway/tree/main/internal/gapi"
click node_circle_client "https://github.com/zvash/bgmood-api-gateway/blob/main/internal/client/circle_service_client.go"
click node_circle_contract "https://github.com/zvash/bgmood-api-gateway/blob/main/internal/cpb/service_circles_grpc.pb.go"
click node_file_client "https://github.com/zvash/bgmood-api-gateway/blob/main/internal/client/file_service_client.go"
click node_file_contract "https://github.com/zvash/bgmood-api-gateway/blob/main/internal/filepb/service_file_grpc.pb.go"
click node_metrics "https://github.com/zvash/bgmood-api-gateway/blob/main/internal/prom/server_metrics.go"
click node_metrics_endpoint "https://github.com/zvash/bgmood-api-gateway/blob/main/main.go"
click node_config "https://github.com/zvash/bgmood-api-gateway/blob/main/internal/util/config.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_server,node_handlers,node_api_contract,node_caller toneBlue
class node_auth_handlers,node_auth_context,node_auth_client,node_auth_contract toneAmber
class node_circle_handlers,node_circle_client,node_circle_contract,node_file_client,node_file_contract toneMint
class node_metrics,node_metrics_endpoint,node_config toneRose
class node_auth_service,node_circle_service toneIndigo
```

## Components

### Gateway API

- [gRPC server](https://github.com/zvash/bgmood-api-gateway/blob/main/main.go): `main.go`
- [API handlers](https://github.com/zvash/bgmood-api-gateway/tree/main/internal/gapi): `internal/gapi`
- [App API contract](https://github.com/zvash/bgmood-api-gateway/blob/main/internal/pb/api_service_grpc.pb.go): `internal/pb/api_service_grpc.pb.go`

### Identity

- [Auth handlers](https://github.com/zvash/bgmood-api-gateway/blob/main/internal/gapi/rpc_auth_service_methods.go): `internal/gapi/rpc_auth_service_methods.go`
- [Request context](https://github.com/zvash/bgmood-api-gateway/blob/main/internal/gapi/client_context.go): `internal/gapi/client_context.go`
- [Auth client](https://github.com/zvash/bgmood-api-gateway/blob/main/internal/client/auth_service_client.go): `internal/client/auth_service_client.go`
- [Auth RPC contract](https://github.com/zvash/bgmood-api-gateway/blob/main/internal/authpb/service_auth_grpc.pb.go): `internal/authpb/service_auth_grpc.pb.go`

### Circles and mood

- [Circle and mood handlers](https://github.com/zvash/bgmood-api-gateway/tree/main/internal/gapi): `internal/gapi`
- [Circle client](https://github.com/zvash/bgmood-api-gateway/blob/main/internal/client/circle_service_client.go): `internal/client/circle_service_client.go`
- [Circles RPC contract](https://github.com/zvash/bgmood-api-gateway/blob/main/internal/cpb/service_circles_grpc.pb.go): `internal/cpb/service_circles_grpc.pb.go`
- [File client](https://github.com/zvash/bgmood-api-gateway/blob/main/internal/client/file_service_client.go): `internal/client/file_service_client.go`
- [File RPC contract](https://github.com/zvash/bgmood-api-gateway/blob/main/internal/filepb/service_file_grpc.pb.go): `internal/filepb/service_file_grpc.pb.go`

### Runtime and telemetry

- [Server metrics](https://github.com/zvash/bgmood-api-gateway/blob/main/internal/prom/server_metrics.go): `internal/prom/server_metrics.go`
- [Metrics endpoint](https://github.com/zvash/bgmood-api-gateway/blob/main/main.go): `main.go`
- [Runtime config](https://github.com/zvash/bgmood-api-gateway/blob/main/internal/util/config.go): `internal/util/config.go`

### Other components

- **gRPC client**
- **Auth service**
- **Circles service**

## Connections

- gRPC client → gRPC server: calls gRPC
- gRPC server → App API contract: registers API
- gRPC server → API handlers: serves requests
- gRPC server → Server metrics: instruments RPCs
- gRPC server → Metrics endpoint: starts endpoint
- gRPC server → Runtime config: loads config
- API handlers → Auth handlers: dispatches auth
- Auth handlers → Request context: builds context
- Auth handlers → Auth client: forwards auth RPCs
- Auth client → Auth RPC contract: invokes RPCs
- Auth RPC contract → Auth service: sends RPCs
- API handlers → Circle and mood handlers: dispatches app RPCs
- Circle and mood handlers → Circle client: forwards circle RPCs
- Circle client → Circles RPC contract: invokes RPCs
- Circles RPC contract → Circles service: sends RPCs
- Metrics endpoint → gRPC client: exposes metrics