# lolo179/billmate-app architecture

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

- Interactive diagram: https://gitdiagram.com/lolo179/billmate-app
- Repository: https://github.com/lolo179/billmate-app

## Overview

##### Primary request path
End users interact with the React frontend. The frontend sends login requests to the auth service, then uses the returned JWT for protected operations. Business API traffic for billing goes through the API Gateway, which acts as the single entry point and enforces authentication before forwarding requests downstream.

##### Auth service boundary
`auth-service` owns user registration and login. It persists users with Spring Data and exposes a small REST API for credential-based access. Its main output is a JWT issued by `JwtService`, which becomes the security token used across the rest of the platform.

##### Gateway boundary
`api-gateway` is a Spring Cloud Gateway service with reactive filters. Its key responsibilities are JWT validation, request routing, and correlation ID propagation. It sits between clients and protected backend services, so it is an architectural control point rather than a business service.

##### Billing service core
`billing-service` is the main domain service and is explicitly organized in hexagonal architecture. The domain layer contains client/invoice models, use-case ports, commands, and outbound ports. The application layer contains use-case implementations, and infrastructure contains all adapters for REST, persistence, PDF generation, Kafka publishing, and cross-cutting filters.

##### Billing data flow
Incoming REST requests hit generated/handwritten controllers in the infrastructure layer, are mapped into DTOs and commands, then routed into application use cases. Use cases operate on domain objects and call outbound ports for persistence, PDF generation, or event publication. This keeps business logic isolated from Spring, JPA, and transport concerns.

##### Billing cross-cutting capabilities
Billing includes idempotency support via a Caffeine-backed idempotency store and filter, which suggests some operations are intended to be safely retried. It also generates PDFs through a dedicated adapter, so invoice download is treated as a separate infrastructure concern rather than a core domain responsibility.

##### Event-driven integration
When invoices are created or emitted in billing, an `InvoiceCreatedEvent` is published through the Kafka outbound port and Kafka adapter. `notification-service` consumes that event and acts as a downstream listener for email-style notifications. This is the only asynchronous service-to-service path in the system.

##### Frontend role
`frontend-service` is a Vite + React + TypeScript SPA. Its architecture mirrors clean boundaries: application use cases call API ports, infrastructure adapters implement HTTP and token storage, and UI pages/components consume those use cases. It is the only browser-facing runtime and likely talks to auth plus the gateway-backed billing APIs.

##### Shared observability and runtime plumbing
The repo includes Docker Compose stacks for Kafka and observability. Logging is standardized through Logback across services, and correlation ID filters appear in multiple backends to support request tracing across service boundaries. Grafana/Loki/Promtail are the main observability tools present.

##### Delivery and verification
CI is split per service with dedicated GitHub Actions workflows, plus a full-stack Playwright E2E pipeline. On `main`, the repo builds/pushes images and then deploys only after CI and E2E succeed. This indicates the architecture is meant to be validated as an integrated system, not just per-service units.

##### External infrastructure
PostgreSQL is the primary durable store for auth and billing. Kafka is the event backbone for invoice notifications. Docker Compose is used to assemble local environments, while GitHub Actions and EC2 are the CI/CD/deployment runtime surfaces.

Main entry points: [`.github/workflows/deploy.yaml`](https://github.com/lolo179/billmate-app/blob/main/.github/workflows/deploy.yaml) (CI/CD), [`billing-service/src/main/java/com/billMate/billing/application/useCase/CreateInvoiceService.java`](https://github.com/lolo179/billmate-app/blob/main/billing-service/src/main/java/com/billMate/billing/application/useCase/CreateInvoiceService.java) (Use cases), [`api-gateway/src/main/java/com/billMate/gateway/GatewayApplication.java`](https://github.com/lolo179/billmate-app/blob/main/api-gateway/src/main/java/com/billMate/gateway/GatewayApplication.java) (API Gateway), [`auth-service/src/main/java/com/billMate/auth/AuthServiceApplication.java`](https://github.com/lolo179/billmate-app/blob/main/auth-service/src/main/java/com/billMate/auth/AuthServiceApplication.java) (Auth Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_frontend["Frontend SPA<br/>vite react ts<br/>[main.tsx]"]
  node_frontend_app["UI flows<br/>react app layer<br/>[LoginPage.tsx]"]
  node_frontend_api["API adapters<br/>http ports"]
end

subgraph group_services["Services"]
  node_gateway["API Gateway<br/>spring gateway"]
  node_gateway_filters["Gateway filters<br/>reactive filter"]
  node_auth["Auth Service<br/>spring auth"]
  node_auth_api["Auth API<br/>rest controller"]
  node_auth_jwt["JWT service<br/>token issuer<br/>[JwtService.java]"]
  node_auth_users[("User store<br/>spring data repo")]
  node_billing["Billing Service<br/>hexagonal domain"]
  node_billing_api["REST contract<br/>openapi rest"]
  node_billing_app["Use cases<br/>application services"]
  node_billing_domain{{"Domain model<br/>entities ports<br/>[Invoice.java]"}}
  node_billing_rest["REST adapters<br/>controllers mappers"]
  node_billing_persistence[("Persistence<br/>jpa postgres")]
  node_billing_pdf["PDF adapter<br/>document generation"]
  node_billing_kafka["Kafka publisher<br/>event adapter"]
  node_notification["Notification Service<br/>spring listener"]
end

subgraph group_infra["Shared Infra"]
  node_kafka["Kafka<br/>event bus"]
  node_postgres[("PostgreSQL<br/>durable store<br/>[create-tables.sql]")]
  node_observability["Observability<br/>logs metrics"]
  node_ci_cd["CI/CD<br/>github actions<br/>[deploy.yaml]"]
end

node_frontend -->|"renders"| node_frontend_app
node_frontend_app -->|"calls"| node_frontend_api
node_frontend_api -->|"login"| node_auth
node_frontend_api -->|"billing api"| node_gateway
node_gateway -->|"enforces"| node_gateway_filters
node_gateway -->|"routes"| node_billing
node_auth -->|"exposes"| node_auth_api
node_auth_api -->|"issues"| node_auth_jwt
node_auth_api -->|"persists"| node_auth_users
node_auth_users -->|"reads/writes"| node_postgres
node_billing -->|"contracts"| node_billing_api
node_billing_api -->|"implements"| node_billing_rest
node_billing_rest -->|"invokes"| node_billing_app
node_billing_app -->|"orchestrates"| node_billing_domain
node_billing_app -->|"loads/saves"| node_billing_persistence
node_billing_app -->|"generates"| node_billing_pdf
node_billing_app -->|"publishes"| node_billing_kafka
node_billing_persistence -->|"stores"| node_postgres
node_billing_kafka -->|"publishes"| node_kafka
node_notification -->|"consumes"| node_kafka
node_billing -.->|"logs"| node_observability
node_auth -.->|"logs"| node_observability
node_gateway -.->|"logs"| node_observability
node_ci_cd -.->|"builds"| node_frontend
node_ci_cd -.->|"builds"| node_auth
node_ci_cd -.->|"builds"| node_gateway
node_ci_cd -.->|"builds"| node_billing
node_ci_cd -.->|"builds"| node_notification
node_ci_cd -.->|"assembles"| node_kafka

click node_frontend "https://github.com/lolo179/billmate-app/blob/main/frontend-service/src/main.tsx"
click node_frontend_app "https://github.com/lolo179/billmate-app/blob/main/frontend-service/src/ui/pages/LoginPage.tsx"
click node_frontend_api "https://github.com/lolo179/billmate-app/blob/main/frontend-service/src/infrastructure/adapters/AuthHttpApiAdapter.ts"
click node_gateway "https://github.com/lolo179/billmate-app/blob/main/api-gateway/src/main/java/com/billMate/gateway/GatewayApplication.java"
click node_gateway_filters "https://github.com/lolo179/billmate-app/blob/main/api-gateway/src/main/java/com/billMate/gateway/filter/AuthenticationFilter.java"
click node_auth "https://github.com/lolo179/billmate-app/blob/main/auth-service/src/main/java/com/billMate/auth/AuthServiceApplication.java"
click node_auth_api "https://github.com/lolo179/billmate-app/blob/main/auth-service/src/main/java/com/billMate/auth/controller/AuthController.java"
click node_auth_jwt "https://github.com/lolo179/billmate-app/blob/main/auth-service/src/main/java/com/billMate/auth/service/JwtService.java"
click node_auth_users "https://github.com/lolo179/billmate-app/blob/main/auth-service/src/main/java/com/billMate/auth/repository/UserRepository.java"
click node_billing "https://github.com/lolo179/billmate-app/blob/main/billing-service/src/main/java/com/billMate/billing/BillServiceApplication.java"
click node_billing_api "https://github.com/lolo179/billmate-app/blob/main/billing-service/contract/contract-billing.yaml"
click node_billing_app "https://github.com/lolo179/billmate-app/blob/main/billing-service/src/main/java/com/billMate/billing/application/useCase/CreateInvoiceService.java"
click node_billing_domain "https://github.com/lolo179/billmate-app/blob/main/billing-service/src/main/java/com/billMate/billing/domain/invoice/model/Invoice.java"
click node_billing_rest "https://github.com/lolo179/billmate-app/blob/main/billing-service/src/main/java/com/billMate/billing/infrastructure/rest/api/InvoiceController.java"
click node_billing_persistence "https://github.com/lolo179/billmate-app/blob/main/billing-service/src/main/java/com/billMate/billing/infrastructure/persistence/adapter/InvoiceJpaAdapter.java"
click node_billing_pdf "https://github.com/lolo179/billmate-app/blob/main/billing-service/src/main/java/com/billMate/billing/infrastructure/pdf/PdfGeneratorAdapter.java"
click node_billing_kafka "https://github.com/lolo179/billmate-app/blob/main/billing-service/src/main/java/com/billMate/billing/infrastructure/kafka/adapter/InvoiceKafkaAdapter.java"
click node_notification "https://github.com/lolo179/billmate-app/blob/main/notification-service/src/main/java/com/billMate/notification/NotificationServiceApplication.java"
click node_kafka "https://github.com/lolo179/billmate-app/blob/main/kafka/docker-compose.yaml"
click node_postgres "https://github.com/lolo179/billmate-app/blob/main/scripts/create-tables.sql"
click node_observability "https://github.com/lolo179/billmate-app/blob/main/observability/docker-compose.yaml"
click node_ci_cd "https://github.com/lolo179/billmate-app/blob/main/.github/workflows/deploy.yaml"

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_frontend,node_frontend_app,node_frontend_api toneBlue
class node_gateway,node_gateway_filters,node_auth,node_auth_api,node_auth_jwt,node_auth_users,node_billing,node_billing_api,node_billing_app,node_billing_domain,node_billing_rest,node_billing_persistence,node_billing_pdf,node_billing_kafka,node_notification toneAmber
class node_kafka,node_postgres,node_observability,node_ci_cd toneMint
```

## Components

### Clients

Browser and test-facing entrypoints

- [Frontend SPA](https://github.com/lolo179/billmate-app/blob/main/frontend-service/src/main.tsx): vite react ts · Browser UI for login and billing workflows · `frontend-service/src/main.tsx`
- [UI flows](https://github.com/lolo179/billmate-app/blob/main/frontend-service/src/ui/pages/LoginPage.tsx): react app layer · Pages, routing, and user-facing workflow composition · `frontend-service/src/ui/pages/LoginPage.tsx`
- [API adapters](https://github.com/lolo179/billmate-app/blob/main/frontend-service/src/infrastructure/adapters/AuthHttpApiAdapter.ts): http ports · HTTP clients and token storage adapters used by the SPA · `frontend-service/src/infrastructure/adapters/AuthHttpApiAdapter.ts`

### Services

Core runtime services

- [API Gateway](https://github.com/lolo179/billmate-app/blob/main/api-gateway/src/main/java/com/billMate/gateway/GatewayApplication.java): spring gateway · Edge control point for protected backend traffic · `api-gateway/src/main/java/com/billMate/gateway/GatewayApplication.java`
- [Gateway filters](https://github.com/lolo179/billmate-app/blob/main/api-gateway/src/main/java/com/billMate/gateway/filter/AuthenticationFilter.java): reactive filter · JWT validation and correlation ID propagation · `api-gateway/src/main/java/com/billMate/gateway/filter/AuthenticationFilter.java`
- [Auth Service](https://github.com/lolo179/billmate-app/blob/main/auth-service/src/main/java/com/billMate/auth/AuthServiceApplication.java): spring auth · Registration, login, and JWT issuance · `auth-service/src/main/java/com/billMate/auth/AuthServiceApplication.java`
- [Auth API](https://github.com/lolo179/billmate-app/blob/main/auth-service/src/main/java/com/billMate/auth/controller/AuthController.java): rest controller · Credential-based registration and login endpoints · `auth-service/src/main/java/com/billMate/auth/controller/AuthController.java`
- [JWT service](https://github.com/lolo179/billmate-app/blob/main/auth-service/src/main/java/com/billMate/auth/service/JwtService.java): token issuer · Creates signed tokens consumed across the platform · `auth-service/src/main/java/com/billMate/auth/service/JwtService.java`
- [User store](https://github.com/lolo179/billmate-app/blob/main/auth-service/src/main/java/com/billMate/auth/repository/UserRepository.java): spring data repo · Persistence boundary for users and roles · `auth-service/src/main/java/com/billMate/auth/repository/UserRepository.java`
- [Billing Service](https://github.com/lolo179/billmate-app/blob/main/billing-service/src/main/java/com/billMate/billing/BillServiceApplication.java): hexagonal domain · Main business service for clients and invoices · `billing-service/src/main/java/com/billMate/billing/BillServiceApplication.java`
- [REST contract](https://github.com/lolo179/billmate-app/blob/main/billing-service/contract/contract-billing.yaml): openapi rest · Contract-first HTTP boundary and controllers · `billing-service/contract/contract-billing.yaml`
- [Use cases](https://github.com/lolo179/billmate-app/blob/main/billing-service/src/main/java/com/billMate/billing/application/useCase/CreateInvoiceService.java): application services · Orchestrates client and invoice operations · `billing-service/src/main/java/com/billMate/billing/application/useCase/CreateInvoiceService.java`
- [Domain model](https://github.com/lolo179/billmate-app/blob/main/billing-service/src/main/java/com/billMate/billing/domain/invoice/model/Invoice.java): entities ports · Client, invoice, commands, events, and outbound ports · `billing-service/src/main/java/com/billMate/billing/domain/invoice/model/Invoice.java`
- [REST adapters](https://github.com/lolo179/billmate-app/blob/main/billing-service/src/main/java/com/billMate/billing/infrastructure/rest/api/InvoiceController.java): controllers mappers · HTTP DTOs, controllers, and request mapping · `billing-service/src/main/java/com/billMate/billing/infrastructure/rest/api/InvoiceController.java`
- [Persistence](https://github.com/lolo179/billmate-app/blob/main/billing-service/src/main/java/com/billMate/billing/infrastructure/persistence/adapter/InvoiceJpaAdapter.java): jpa postgres · JPA entities, repositories, and persistence mappers · `billing-service/src/main/java/com/billMate/billing/infrastructure/persistence/adapter/InvoiceJpaAdapter.java`
- [PDF adapter](https://github.com/lolo179/billmate-app/blob/main/billing-service/src/main/java/com/billMate/billing/infrastructure/pdf/PdfGeneratorAdapter.java): document generation · Invoice PDF rendering as an infrastructure concern · `billing-service/src/main/java/com/billMate/billing/infrastructure/pdf/PdfGeneratorAdapter.java`
- [Kafka publisher](https://github.com/lolo179/billmate-app/blob/main/billing-service/src/main/java/com/billMate/billing/infrastructure/kafka/adapter/InvoiceKafkaAdapter.java): event adapter · Publishes invoice-created events to the bus · `billing-service/src/main/java/com/billMate/billing/infrastructure/kafka/adapter/InvoiceKafkaAdapter.java`
- [Notification Service](https://github.com/lolo179/billmate-app/blob/main/notification-service/src/main/java/com/billMate/notification/NotificationServiceApplication.java): spring listener · Consumes billing events for downstream notifications · `notification-service/src/main/java/com/billMate/notification/NotificationServiceApplication.java`

### Shared Infra

Eventing, storage, observability, and delivery

- [Kafka](https://github.com/lolo179/billmate-app/blob/main/kafka/docker-compose.yaml): event bus · Asynchronous integration backbone for invoice events · `kafka/docker-compose.yaml`
- [PostgreSQL](https://github.com/lolo179/billmate-app/blob/main/scripts/create-tables.sql): durable store · Primary database for auth and billing · `scripts/create-tables.sql`
- [Observability](https://github.com/lolo179/billmate-app/blob/main/observability/docker-compose.yaml): logs metrics · Grafana, Loki, and Promtail deployment stack · `observability/docker-compose.yaml`
- [CI/CD](https://github.com/lolo179/billmate-app/blob/main/.github/workflows/deploy.yaml): github actions · Service pipelines, E2E checks, and deployment workflow · `.github/workflows/deploy.yaml`

## Connections

- Frontend SPA → UI flows: renders · SPA shell composes pages and routes
- UI flows → API adapters: calls · UI flows invoke HTTP and token ports
- API adapters → Auth Service: login · Browser authentication requests go to auth service
- API adapters → API Gateway: billing api · Protected billing requests go through the edge gateway
- API Gateway → Gateway filters: enforces · Gateway applies authentication and correlation filters
- API Gateway → Billing Service: routes · Forwards authenticated traffic to billing service
- Auth Service → Auth API: exposes · REST endpoints for register and login
- Auth API → JWT service: issues · Successful login returns JWT tokens
- Auth API → User store: persists · User records are stored through Spring Data
- User store → PostgreSQL: reads/writes · Auth data is stored in PostgreSQL
- Billing Service → REST contract: contracts · OpenAPI drives the public HTTP boundary
- REST contract → REST adapters: implements · Generated and handwritten controllers implement the API
- REST adapters → Use cases: invokes · REST adapters translate requests into use cases
- Use cases → Domain model: orchestrates · Application services operate on domain models and ports
- Use cases → Persistence: loads/saves · Use cases persist aggregates through ports
- Use cases → PDF adapter: generates · Invoice downloads are delegated to PDF generation
- Use cases → Kafka publisher: publishes · Invoice creation can emit events to Kafka
- Persistence → PostgreSQL: stores · Billing data is backed by PostgreSQL
- Kafka publisher → Kafka: publishes · InvoiceCreatedEvent flows onto the event bus
- Notification Service → Kafka: consumes · Notification service listens for invoice events
- Billing Service → Observability: logs · Services share standardized logging and tracing support
- Auth Service → Observability: logs · Auth service emits structured logs for shared observability
- API Gateway → Observability: logs · Gateway participates in request tracing and logs
- CI/CD → Frontend SPA: builds · GitHub Actions validates and builds the SPA
- CI/CD → Auth Service: builds · Dedicated workflow validates auth service
- CI/CD → API Gateway: builds · Dedicated workflow validates gateway service
- CI/CD → Billing Service: builds · Dedicated workflow validates billing service
- CI/CD → Notification Service: builds · Dedicated workflow validates notification service
- CI/CD → Kafka: assembles · Local and CI stacks include Kafka
