How lolo179/billmate-app works
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: deploy.yaml CI/CD · CreateInvoiceService.java Use cases · GatewayApplication.java API Gateway · AuthServiceApplication.java Auth Service
Components 22
Clients
Browser and test-facing entrypoints
- Frontend SPA · Browser UI for login and billing workflows
frontend-service/src/main.tsx - UI flows · Pages, routing, and user-facing workflow composition
frontend-service/src/ui/pages/LoginPage.tsx - API adapters · HTTP clients and token storage adapters used by the SPA
frontend-service/src/infrastructure/adapters/AuthHttpApiAdapter.ts
Services
Core runtime services
- API Gateway · Edge control point for protected backend traffic
api-gateway/src/main/java/com/billMate/gateway/GatewayApplication.java - Gateway filters · JWT validation and correlation ID propagation
api-gateway/src/main/java/com/billMate/gateway/filter/AuthenticationFilter.java - Auth Service · Registration, login, and JWT issuance
auth-service/src/main/java/com/billMate/auth/AuthServiceApplication.java - Auth API · Credential-based registration and login endpoints
auth-service/src/main/java/com/billMate/auth/controller/AuthController.java - JWT service · Creates signed tokens consumed across the platform
auth-service/src/main/java/com/billMate/auth/service/JwtService.java - User store · Persistence boundary for users and roles
auth-service/src/main/java/com/billMate/auth/repository/UserRepository.java - Billing Service · Main business service for clients and invoices
billing-service/src/main/java/com/billMate/billing/BillServiceApplication.java - REST contract · Contract-first HTTP boundary and controllers
billing-service/contract/contract-billing.yaml - Use cases · Orchestrates client and invoice operations
billing-service/src/main/java/com/billMate/billing/application/useCase/CreateInvoiceService.java - Domain model · Client, invoice, commands, events, and outbound ports
billing-service/src/main/java/com/billMate/billing/domain/invoice/model/Invoice.java - REST adapters · HTTP DTOs, controllers, and request mapping
billing-service/src/main/java/com/billMate/billing/infrastructure/rest/api/InvoiceController.java - Persistence · JPA entities, repositories, and persistence mappers
billing-service/src/main/java/com/billMate/billing/infrastructure/persistence/adapter/InvoiceJpaAdapter.java - PDF adapter · Invoice PDF rendering as an infrastructure concern
billing-service/src/main/java/com/billMate/billing/infrastructure/pdf/PdfGeneratorAdapter.java - Kafka publisher · Publishes invoice-created events to the bus
billing-service/src/main/java/com/billMate/billing/infrastructure/kafka/adapter/InvoiceKafkaAdapter.java - Notification Service · Consumes billing events for downstream notifications
notification-service/src/main/java/com/billMate/notification/NotificationServiceApplication.java
Shared Infra
Eventing, storage, observability, and delivery
- Kafka · Asynchronous integration backbone for invoice events
kafka/docker-compose.yaml - PostgreSQL · Primary database for auth and billing
scripts/create-tables.sql - Observability · Grafana, Loki, and Promtail deployment stack
observability/docker-compose.yaml - CI/CD · Service pipelines, E2E checks, and deployment workflow
.github/workflows/deploy.yaml
Connections 29
- 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