# projectgammacompany/eduplay-backend architecture

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

- Interactive diagram: https://gitdiagram.com/projectgammacompany/eduplay-backend
- Repository: https://github.com/projectgammacompany/eduplay-backend

## Overview

#### Purpose and entry points
This is a Go microservice backend for EduPlay: user identity, educational events/tasks, file/public-event data, and notifications, fronted by an HTTP gateway. Each Go service starts from `cmd/service/main.go`, notably `eduplay-gateway/cmd/service/main.go`, `eduplay-event/cmd/service/main.go`, and `eduplay-user/cmd/service/main.go`. The separate Python mail service starts at `eduplay-mail/run.py`.

#### HTTP edge and request orchestration
`eduplay-gateway` is the public HTTP boundary. Its application bootstrap and route composition are in `eduplay-gateway/internal/application/application.go` and `eduplay-gateway/internal/http/routers/`. HTTP handlers delegate to gateway use cases, which call downstream gRPC clients rather than directly accessing service databases. Cross-cutting HTTP controls include CORS, logging, request sizing, and token validation in `eduplay-gateway/internal/http/middleware/` and `eduplay-gateway/internal/http/tokens/validation.go`.

#### Event domain service
`eduplay-event` owns the event-authoring and player workflow: events, blocks, tasks, conditions, participation/groups, answers, progression, ratings, favorites, history, and stats. Its RPC boundary is `eduplay-event/internal/rpc/event_handler/handler.go`; business operations are concentrated in `eduplay-event/internal/pkg/usecase/events/`; persistence is behind `eduplay-event/internal/pkg/storage/postgres/postgres.go`. The gateway maps corresponding HTTP operations into this service through `eduplay-gateway/internal/pkg/clients/event/eventClient.go` and `eduplay-gateway/internal/pkg/usecases/event/`.

#### User identity and account lifecycle
`eduplay-user` owns registration, sign-in/out, refresh tokens, profiles, passwords, avatars, verification codes, and account deletion. Its domain models are in `eduplay-user/internal/model/`, RPC implementation in `eduplay-user/internal/rpc/user_handler/handler.go`, and PostgreSQL adapter in `eduplay-user/internal/pkg/storage/postgres/postgres.go`. Gateway user endpoints flow through `eduplay-gateway/internal/pkg/clients/user/usersClient.go` and `eduplay-gateway/internal/pkg/usecases/user/`.

#### Data/files and notifications
`eduplay-data` provides file saving and public-event retrieval, exposing gRPC via `eduplay-data/internal/rpc/data_handler/handler.go` and persisting through `eduplay-data/internal/pkg/storage/postgres/postgres.go`. `eduplay-notification` independently serves notification retrieval/deletion through `eduplay-notification/internal/rpc/notification_handler/handler.go` and `eduplay-notification/internal/pkg/usecase/notification/`. Both are consumed by gateway-specific clients: `eduplay-gateway/internal/pkg/clients/data/dataClient.go` and `eduplay-gateway/internal/pkg/clients/notification/notificationClient.go`.

#### Service contracts and asynchronous boundaries
Service-to-service synchronous communication is gRPC, defined by per-service protobuf contracts such as `eduplay-event/proto/service_events.proto`, `eduplay-user/proto/service_users.proto`, and gateway client contracts under `eduplay-gateway/proto/clients/`. RabbitMQ is an asynchronous integration boundary: user code has a producer at `eduplay-user/internal/pkg/usecase/rabbitmq/producer.go`, while event and data include consumers at `eduplay-event/internal/pkg/usecase/rabbitmq/consumer.go` and `eduplay-data/internal/pkg/usecase/rabbitmq/consumer.go`. Email delivery is delegated from user logic to the mail client at `eduplay-user/internal/pkg/clients/email/client.go`, with implementation in `eduplay-mail/mail/srv.py`.

#### Persistence and deployment
PostgreSQL schema is partitioned by domain in `database/users.sql`, `database/events.sql`, `database/files.sql`, and `database/notification.sql`. Local multi-container composition is represented by `docker-compose.yml`; each service has a Dockerfile. Kubernetes deployment manifests cover gateway, event, user, notification, and mail under `k8s/app/`, with public ingress specifically at `k8s/app/eduplay-gateway/ingress.yaml`. Argo bootstrap is defined in `k8s/bootstrap/argo-app.yaml`.

Main entry points: [`docker-compose.yml`](https://github.com/projectgammacompany/eduplay-backend/blob/main/docker-compose.yml) (Container deployment), [`eduplay-gateway/internal/pkg/clients/data/dataClient.go`](https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-gateway/internal/pkg/clients/data/dataClient.go) (Data & notification clients), [`eduplay-user/internal/pkg/usecase/rabbitmq/producer.go`](https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-user/internal/pkg/usecase/rabbitmq/producer.go) (RabbitMQ), [`eduplay-event/internal/rpc/event_handler/handler.go`](https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-event/internal/rpc/event_handler/handler.go) (Event RPC service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["HTTP Gateway"]
  node_public(("Public clients<br/>HTTP clients"))
  node_gateway_routes["Gateway routes &amp; middleware<br/>HTTP boundary"]
  node_gateway_app["Gateway application<br/>bootstrap<br/>[application.go]"]
  node_gateway_event["Event gateway use cases"]
  node_gateway_user["User gateway use cases"]
  node_gateway_clients["Data &amp; notification clients<br/>gRPC clients<br/>[dataClient.go]"]
end

subgraph group_services["Domain Services"]
  node_event_rpc["Event RPC service<br/>gRPC handler<br/>[handler.go]"]
  node_event_usecases["Event workflow<br/>domain use cases"]
  node_event_store[("Event storage<br/>PostgreSQL adapter<br/>[postgres.go]")]
  node_user_rpc["User RPC service<br/>gRPC handler<br/>[handler.go]"]
  node_user_domain["Account lifecycle<br/>identity domain"]
  node_user_store[("User storage<br/>PostgreSQL adapter<br/>[postgres.go]")]
  node_data_rpc["Data RPC service<br/>gRPC handler<br/>[handler.go]"]
  node_data_store[("Data storage<br/>PostgreSQL adapter<br/>[postgres.go]")]
  node_notification_rpc["Notification RPC service<br/>gRPC handler<br/>[handler.go]"]
  node_notification_usecases["Notification use cases<br/>domain use cases"]
end

subgraph group_platform["Integration &amp; Data"]
  node_grpc_contracts["Service protobuf contracts"]
  node_rabbitmq["RabbitMQ<br/>message broker<br/>[producer.go]"]
  node_mail["Mail service<br/>Python service<br/>[srv.py]"]
  node_postgres[("Domain PostgreSQL schemas<br/>database schemas<br/>[users.sql]")]
  node_deployment{{"Container deployment<br/>Compose and Kubernetes<br/>[docker-compose.yml]"}}
end

node_public -->|"HTTPS"| node_gateway_routes
node_gateway_app -->|"composes"| node_gateway_routes
node_gateway_routes -->|"event requests"| node_gateway_event
node_gateway_routes -->|"account requests"| node_gateway_user
node_gateway_routes -->|"data and notifications"| node_gateway_clients
node_gateway_event -->|"gRPC"| node_event_rpc
node_gateway_user -->|"gRPC"| node_user_rpc
node_gateway_clients -->|"gRPC"| node_data_rpc
node_gateway_clients -->|"gRPC"| node_notification_rpc
node_event_rpc -->|"delegates"| node_event_usecases
node_event_usecases -->|"persists"| node_event_store
node_user_rpc -->|"delegates"| node_user_domain
node_user_domain -->|"persists"| node_user_store
node_data_rpc -->|"persists"| node_data_store
node_notification_rpc -->|"delegates"| node_notification_usecases
node_gateway_event -.->|"uses API"| node_grpc_contracts
node_gateway_user -.->|"uses API"| node_grpc_contracts
node_user_domain -.->|"publishes"| node_rabbitmq
node_rabbitmq -.->|"consumed by"| node_event_usecases
node_rabbitmq -.->|"consumed by"| node_data_rpc
node_user_domain -->|"email client"| node_mail
node_event_store -.->|"events schema"| node_postgres
node_user_store -.->|"users schema"| node_postgres
node_data_store -.->|"files schema"| node_postgres
node_deployment -.->|"deploys"| node_gateway_app
node_deployment -.->|"deploys"| node_event_rpc
node_deployment -.->|"deploys"| node_user_rpc
node_deployment -.->|"deploys"| node_notification_rpc
node_deployment -.->|"deploys"| node_mail

click node_gateway_app "https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-gateway/internal/application/application.go"
click node_gateway_clients "https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-gateway/internal/pkg/clients/data/dataClient.go"
click node_event_rpc "https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-event/internal/rpc/event_handler/handler.go"
click node_event_store "https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-event/internal/pkg/storage/postgres/postgres.go"
click node_user_rpc "https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-user/internal/rpc/user_handler/handler.go"
click node_user_store "https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-user/internal/pkg/storage/postgres/postgres.go"
click node_data_rpc "https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-data/internal/rpc/data_handler/handler.go"
click node_data_store "https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-data/internal/pkg/storage/postgres/postgres.go"
click node_notification_rpc "https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-notification/internal/rpc/notification_handler/handler.go"
click node_grpc_contracts "https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-event/proto/service_events.proto"
click node_rabbitmq "https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-user/internal/pkg/usecase/rabbitmq/producer.go"
click node_mail "https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-mail/mail/srv.py"
click node_postgres "https://github.com/projectgammacompany/eduplay-backend/blob/main/database/users.sql"
click node_deployment "https://github.com/projectgammacompany/eduplay-backend/blob/main/docker-compose.yml"

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_public,node_gateway_routes,node_gateway_app,node_gateway_event,node_gateway_user,node_gateway_clients toneBlue
class node_event_rpc,node_event_usecases,node_event_store,node_user_rpc,node_user_domain,node_user_store,node_data_rpc,node_data_store,node_notification_rpc,node_notification_usecases toneAmber
class node_grpc_contracts,node_rabbitmq,node_mail,node_postgres,node_deployment toneMint
```

## Components

### HTTP Gateway

Public API and downstream gRPC orchestration.

- **Public clients**: HTTP clients
- **Gateway routes & middleware**: HTTP boundary · Routes apply token validation and HTTP controls.
- [Gateway application](https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-gateway/internal/application/application.go): bootstrap · `eduplay-gateway/internal/application/application.go`
- **Event gateway use cases**: use cases
- **User gateway use cases**: use cases
- [Data & notification clients](https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-gateway/internal/pkg/clients/data/dataClient.go): gRPC clients · `eduplay-gateway/internal/pkg/clients/data/dataClient.go`

### Domain Services

Independently owned gRPC domains.

- [Event RPC service](https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-event/internal/rpc/event_handler/handler.go): gRPC handler · `eduplay-event/internal/rpc/event_handler/handler.go`
- **Event workflow**: domain use cases · Authors and runs events, tasks, progression, and player activity.
- [Event storage](https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-event/internal/pkg/storage/postgres/postgres.go): PostgreSQL adapter · `eduplay-event/internal/pkg/storage/postgres/postgres.go`
- [User RPC service](https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-user/internal/rpc/user_handler/handler.go): gRPC handler · `eduplay-user/internal/rpc/user_handler/handler.go`
- **Account lifecycle**: identity domain · Registration, authentication, profiles, credentials, and verification.
- [User storage](https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-user/internal/pkg/storage/postgres/postgres.go): PostgreSQL adapter · `eduplay-user/internal/pkg/storage/postgres/postgres.go`
- [Data RPC service](https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-data/internal/rpc/data_handler/handler.go): gRPC handler · Provides file saving and public-event retrieval. · `eduplay-data/internal/rpc/data_handler/handler.go`
- [Data storage](https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-data/internal/pkg/storage/postgres/postgres.go): PostgreSQL adapter · `eduplay-data/internal/pkg/storage/postgres/postgres.go`
- [Notification RPC service](https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-notification/internal/rpc/notification_handler/handler.go): gRPC handler · `eduplay-notification/internal/rpc/notification_handler/handler.go`
- **Notification use cases**: domain use cases · Retrieves and deletes notifications.

### Integration & Data

Shared asynchronous, persistence, and deployment boundaries.

- [Service protobuf contracts](https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-event/proto/service_events.proto): protobuf · Defines synchronous service APIs. · `eduplay-event/proto/service_events.proto`
- [RabbitMQ](https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-user/internal/pkg/usecase/rabbitmq/producer.go): message broker · Asynchronous user-to-event/data integration boundary. · `eduplay-user/internal/pkg/usecase/rabbitmq/producer.go`
- [Mail service](https://github.com/projectgammacompany/eduplay-backend/blob/main/eduplay-mail/mail/srv.py): Python service · Delivers email requested by user workflows. · `eduplay-mail/mail/srv.py`
- [Domain PostgreSQL schemas](https://github.com/projectgammacompany/eduplay-backend/blob/main/database/users.sql): database schemas · Separate users, events, files, and notification schemas. · `database/users.sql`
- [Container deployment](https://github.com/projectgammacompany/eduplay-backend/blob/main/docker-compose.yml): Compose and Kubernetes · Local composition, Kubernetes workloads, ingress, and Argo bootstrap. · `docker-compose.yml`

## Connections

- Public clients → Gateway routes & middleware: HTTPS
- Gateway application → Gateway routes & middleware: composes
- Gateway routes & middleware → Event gateway use cases: event requests
- Gateway routes & middleware → User gateway use cases: account requests
- Gateway routes & middleware → Data & notification clients: data and notifications
- Event gateway use cases → Event RPC service: gRPC
- User gateway use cases → User RPC service: gRPC
- Data & notification clients → Data RPC service: gRPC
- Data & notification clients → Notification RPC service: gRPC
- Event RPC service → Event workflow: delegates
- Event workflow → Event storage: persists
- User RPC service → Account lifecycle: delegates
- Account lifecycle → User storage: persists
- Data RPC service → Data storage: persists
- Notification RPC service → Notification use cases: delegates
- Event gateway use cases → Service protobuf contracts: uses API
- User gateway use cases → Service protobuf contracts: uses API
- Account lifecycle → RabbitMQ: publishes
- RabbitMQ → Event workflow: consumed by
- RabbitMQ → Data RPC service: consumed by
- Account lifecycle → Mail service: email client
- Event storage → Domain PostgreSQL schemas: events schema
- User storage → Domain PostgreSQL schemas: users schema
- Data storage → Domain PostgreSQL schemas: files schema
- Container deployment → Gateway application: deploys
- Container deployment → Event RPC service: deploys
- Container deployment → User RPC service: deploys
- Container deployment → Notification RPC service: deploys
- Container deployment → Mail service: deploys