# lele97/pagatu-backend architecture

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

- Interactive diagram: https://gitdiagram.com/lele97/pagatu-backend
- Repository: https://github.com/lele97/pagatu-backend

## Overview

PagaTu is a Java/Spring backend for coordinating coffee turns, group payments and identity across microservices. A client request enters through the gateway; the documented routing sends it to Auth or Coffee, where users authenticate or manage groups and payments. Coffee also provides balances, rankings, invitations, karma and awards. Auth and Coffee publish events through transactional outboxes and NATS for Mail delivery. The graph follows the README’s documented architecture and sampled calls; several Coffee features and service-discovery links are documented but their implementation was not sampled.

Main entry points: [`gateway-service/src/main/java/com/pagatu/gateway_service/config/GatewayConfig.java`](https://github.com/lele97/pagatu-backend/blob/main/gateway-service/src/main/java/com/pagatu/gateway_service/config/GatewayConfig.java) (API gateway), [`auth/src/main/java/com/pagatu/auth/controller/AuthController.java`](https://github.com/lele97/pagatu-backend/blob/main/auth/src/main/java/com/pagatu/auth/controller/AuthController.java) (Auth endpoints), [`coffee/src/main/java/com/pagatu/coffee/service/OutboxProcessor.java`](https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/service/OutboxProcessor.java) (Transactional outbox), [`auth/src/main/java/com/pagatu/auth/service/AuthService.java`](https://github.com/lele97/pagatu-backend/blob/main/auth/src/main/java/com/pagatu/auth/service/AuthService.java) (Identity and OAuth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge and discovery"]
  node_gateway["API gateway<br/>[GatewayConfig.java]"]
  node_eureka["Service discovery"]
end

subgraph group_identity["Identity service"]
  node_auth_api["Auth endpoints"]
  node_auth_service["Identity and OAuth<br/>[AuthService.java]"]
  node_oauth_service["Provider sign-in<br/>[OAuthService.java]"]
  node_email_verify["Email verification"]
  node_auth_store[("Auth database")]
end

subgraph group_domain["Coffee domain"]
  node_group_api["Group endpoints"]
  node_group_service["Group management<br/>[GroupService.java]"]
  node_payment_api["Payment endpoints"]
  node_payment_service["Turns and payments"]
  node_awards["Karma and awards<br/>[AwardService.java]"]
  node_coffee_store[("Coffee database")]
end

subgraph group_messaging["Events and mail"]
  node_outbox["Transactional outbox"]
  node_nats["NATS messaging<br/>[NatsPublisher.java]"]
  node_mail_subscriber["Mail subscribers"]
  node_email_service["Email delivery<br/>[EmailService.java]"]
end

node_client(("Web client"))
node_oauth_providers["OAuth providers"]

node_client -->|"sends requests"| node_gateway
node_gateway -->|"routes requests"| node_auth_api
node_gateway -->|"routes requests"| node_group_api
node_gateway -.->|"resolves services"| node_eureka
node_auth_api -->|"delegates auth"| node_auth_service
node_auth_api -->|"delegates OAuth"| node_oauth_service
node_auth_api -->|"delegates verification"| node_email_verify
node_auth_service -->|"reads and writes"| node_auth_store
node_oauth_service -->|"reads and writes"| node_auth_store
node_oauth_service -->|"exchanges tokens"| node_oauth_providers
node_email_verify -.->|"persists tokens"| node_auth_store
node_group_api -->|"delegates group actions"| node_group_service
node_group_service -->|"reads and writes"| node_coffee_store
node_payment_api -.->|"delegates payments"| node_payment_service
node_payment_service -->|"updates payment state"| node_coffee_store
node_awards -.->|"reads payment history"| node_coffee_store
node_auth_service -.->|"records mail events"| node_outbox
node_group_service -.->|"records group events"| node_outbox
node_payment_service -.->|"records payment events"| node_outbox
node_outbox -.->|"publishes events"| node_nats
node_nats -.->|"dispatches events"| node_mail_subscriber
node_mail_subscriber -.->|"handles notifications"| node_email_service

click node_gateway "https://github.com/lele97/pagatu-backend/blob/main/gateway-service/src/main/java/com/pagatu/gateway_service/config/GatewayConfig.java"
click node_eureka "https://github.com/lele97/pagatu-backend/blob/main/eureka-server/src/main/java/com/pagatu/eureka_server/EurekaServerApplication.java"
click node_auth_api "https://github.com/lele97/pagatu-backend/blob/main/auth/src/main/java/com/pagatu/auth/controller/AuthController.java"
click node_auth_service "https://github.com/lele97/pagatu-backend/blob/main/auth/src/main/java/com/pagatu/auth/service/AuthService.java"
click node_oauth_service "https://github.com/lele97/pagatu-backend/blob/main/auth/src/main/java/com/pagatu/auth/service/OAuthService.java"
click node_email_verify "https://github.com/lele97/pagatu-backend/blob/main/auth/src/main/java/com/pagatu/auth/service/EmailVerificationService.java"
click node_auth_store "https://github.com/lele97/pagatu-backend/blob/main/auth/src/main/java/com/pagatu/auth/repository/UserRepository.java"
click node_group_api "https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/controller/GroupController.java"
click node_group_service "https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/service/GroupService.java"
click node_payment_api "https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/controller/PaymentController.java"
click node_payment_service "https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/service/PaymentService.java"
click node_awards "https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/service/AwardService.java"
click node_coffee_store "https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/repository/GroupRepository.java"
click node_outbox "https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/service/OutboxProcessor.java"
click node_nats "https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/nats/NatsPublisher.java"
click node_mail_subscriber "https://github.com/lele97/pagatu-backend/blob/main/mail/src/main/java/com/pagatu/mail/nats/NatsSubscriber.java"
click node_email_service "https://github.com/lele97/pagatu-backend/blob/main/mail/src/main/java/com/pagatu/mail/service/EmailService.java"

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_gateway,node_eureka,node_client toneBlue
class node_auth_api,node_auth_service,node_oauth_service,node_email_verify,node_auth_store toneAmber
class node_group_api,node_group_service,node_payment_api,node_payment_service,node_awards,node_coffee_store toneMint
class node_outbox,node_nats,node_mail_subscriber,node_email_service toneRose
class node_oauth_providers toneIndigo
```

## Components

### Edge and discovery

- [API gateway](https://github.com/lele97/pagatu-backend/blob/main/gateway-service/src/main/java/com/pagatu/gateway_service/config/GatewayConfig.java): `gateway-service/src/main/java/com/pagatu/gateway_service/config/GatewayConfig.java`
- [Service discovery](https://github.com/lele97/pagatu-backend/blob/main/eureka-server/src/main/java/com/pagatu/eureka_server/EurekaServerApplication.java): `eureka-server/src/main/java/com/pagatu/eureka_server/EurekaServerApplication.java`

### Identity service

- [Auth endpoints](https://github.com/lele97/pagatu-backend/blob/main/auth/src/main/java/com/pagatu/auth/controller/AuthController.java): `auth/src/main/java/com/pagatu/auth/controller/AuthController.java`
- [Identity and OAuth](https://github.com/lele97/pagatu-backend/blob/main/auth/src/main/java/com/pagatu/auth/service/AuthService.java): `auth/src/main/java/com/pagatu/auth/service/AuthService.java`
- [Provider sign-in](https://github.com/lele97/pagatu-backend/blob/main/auth/src/main/java/com/pagatu/auth/service/OAuthService.java): `auth/src/main/java/com/pagatu/auth/service/OAuthService.java`
- [Email verification](https://github.com/lele97/pagatu-backend/blob/main/auth/src/main/java/com/pagatu/auth/service/EmailVerificationService.java): `auth/src/main/java/com/pagatu/auth/service/EmailVerificationService.java`
- [Auth database](https://github.com/lele97/pagatu-backend/blob/main/auth/src/main/java/com/pagatu/auth/repository/UserRepository.java): `auth/src/main/java/com/pagatu/auth/repository/UserRepository.java`

### Coffee domain

- [Group endpoints](https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/controller/GroupController.java): `coffee/src/main/java/com/pagatu/coffee/controller/GroupController.java`
- [Group management](https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/service/GroupService.java): `coffee/src/main/java/com/pagatu/coffee/service/GroupService.java`
- [Payment endpoints](https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/controller/PaymentController.java): `coffee/src/main/java/com/pagatu/coffee/controller/PaymentController.java`
- [Turns and payments](https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/service/PaymentService.java): `coffee/src/main/java/com/pagatu/coffee/service/PaymentService.java`
- [Karma and awards](https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/service/AwardService.java): `coffee/src/main/java/com/pagatu/coffee/service/AwardService.java`
- [Coffee database](https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/repository/GroupRepository.java): `coffee/src/main/java/com/pagatu/coffee/repository/GroupRepository.java`

### Events and mail

- [Transactional outbox](https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/service/OutboxProcessor.java): `coffee/src/main/java/com/pagatu/coffee/service/OutboxProcessor.java`
- [NATS messaging](https://github.com/lele97/pagatu-backend/blob/main/coffee/src/main/java/com/pagatu/coffee/nats/NatsPublisher.java): `coffee/src/main/java/com/pagatu/coffee/nats/NatsPublisher.java`
- [Mail subscribers](https://github.com/lele97/pagatu-backend/blob/main/mail/src/main/java/com/pagatu/mail/nats/NatsSubscriber.java): `mail/src/main/java/com/pagatu/mail/nats/NatsSubscriber.java`
- [Email delivery](https://github.com/lele97/pagatu-backend/blob/main/mail/src/main/java/com/pagatu/mail/service/EmailService.java): `mail/src/main/java/com/pagatu/mail/service/EmailService.java`

### Other components

- **Web client**
- **OAuth providers**

## Connections

- Web client → API gateway: sends requests (evidence: `README.md`)
- API gateway → Auth endpoints: routes requests (evidence: `README.md`)
- API gateway → Group endpoints: routes requests (evidence: `README.md`)
- API gateway → Service discovery: resolves services (evidence: `README.md`)
- Auth endpoints → Identity and OAuth: delegates auth (evidence: `auth/src/main/java/com/pagatu/auth/controller/AuthController.java`)
- Auth endpoints → Provider sign-in: delegates OAuth (evidence: `auth/src/main/java/com/pagatu/auth/controller/AuthController.java`)
- Auth endpoints → Email verification: delegates verification (evidence: `auth/src/main/java/com/pagatu/auth/controller/AuthController.java`)
- Identity and OAuth → Auth database: reads and writes (evidence: `auth/src/main/java/com/pagatu/auth/service/AuthService.java`)
- Provider sign-in → Auth database: reads and writes (evidence: `auth/src/main/java/com/pagatu/auth/service/OAuthService.java`)
- Provider sign-in → OAuth providers: exchanges tokens (evidence: `auth/src/main/java/com/pagatu/auth/service/OAuthService.java`)
- Email verification → Auth database: persists tokens (evidence: `auth/src/main/java/com/pagatu/auth/service/EmailVerificationService.java`)
- Group endpoints → Group management: delegates group actions (evidence: `coffee/src/main/java/com/pagatu/coffee/controller/GroupController.java`)
- Group management → Coffee database: reads and writes (evidence: `coffee/src/main/java/com/pagatu/coffee/service/GroupService.java`)
- Payment endpoints → Turns and payments: delegates payments (evidence: `coffee/src/main/java/com/pagatu/coffee/controller/PaymentController.java`)
- Turns and payments → Coffee database: updates payment state (evidence: `coffee/src/main/java/com/pagatu/coffee/service/PaymentService.java`)
- Karma and awards → Coffee database: reads payment history
- Identity and OAuth → Transactional outbox: records mail events (evidence: `README.md`)
- Group management → Transactional outbox: records group events (evidence: `README.md`)
- Turns and payments → Transactional outbox: records payment events (evidence: `README.md`)
- Transactional outbox → NATS messaging: publishes events (evidence: `README.md`)
- NATS messaging → Mail subscribers: dispatches events (evidence: `README.md`)
- Mail subscribers → Email delivery: handles notifications
