StreamBill

StreamBill is a full-stack, event-driven billing platform built with React, TypeScript, Spring Boot, Apache Kafka, Kafka Streams, PostgreSQL, and Docker.

It processes billing events asynchronously, calculates customer totals in real time, stores audit records, exposes operational metrics, and generates downloadable customer billing statements.

Architecture

React frontend
      ↓
Spring Boot REST API
      ↓
billing-events topic
      ├── Billing consumer → PostgreSQL
      └── Kafka Streams aggregation
                    ↓
        customer-billing-totals topic
                    ↓
             Totals consumer
                    ↓
                PostgreSQL

Features

Frontend

• Billing overview dashboard
• Create billing events
• Paginated event history
• Search and event-type filtering
• Event audit drawer
• Customer totals table
• Downloadable customer statement PDFs
• System health and business metrics
• Automatic refresh
• Responsive dark UI

Backend

• REST event publishing
• Kafka producer and consumers
• Kafka Streams aggregation
• Payment and refund processing
• PostgreSQL persistence
• Duplicate-event protection
• Validation and structured errors
• Retries and dead-letter topic
• Malformed-message handling
• PDF statement generation
• Swagger documentation
• Actuator health checks
• Unit and controller tests

Event Types

Event	Balance effect
PAYMENT_RECEIVED	Adds amount
REFUND_PROCESSED	Subtracts amount
PAYMENT_FAILED	No change
INVOICE_CREATED	No change

Run Locally

Requirements

• Docker Desktop
• Docker Compose

From the project root:

docker compose up --build

Open:

• Frontend: http://localhost:3000
• Swagger: http://localhost:8080/swagger-ui/index.html
• Health: http://localhost:8080/actuator/health

Stop the application:

docker compose down

Example Event

{
  "eventId": "demo-payment-001",
  "customerId": "demo-customer-001",
  "type": "PAYMENT_RECEIVED",
  "amount": 100.00,
  "occurredAt": "2026-08-03T01:30:00Z"
}

API Endpoints

POST /api/billing-events
GET  /api/billing-events
GET  /api/billing-events/{eventId}
GET  /api/billing-events/customer/{customerId}

GET  /api/customer-totals
GET  /api/customer-totals/{customerId}
GET  /api/customer-totals/{customerId}/bill

The bill endpoint returns a downloadable PDF containing the customer's transaction history and current total.

Technology

Frontend: React, TypeScript, Vite, React Router, Recharts, Lucide React, Nginx

Backend: Java 17, Spring Boot, Spring Kafka, Kafka Streams, Spring Data JPA, OpenPDF

Infrastructure: Docker, Docker Compose, Apache Kafka, PostgreSQL

Testing

Backend:

cd backend/streambill-service
./mvnw test

Frontend:

cd frontend
npm install
npm run build

Reliability

• Duplicate events are skipped using eventId
• Failed events are retried
• Repeated failures are sent to billing-events-dlt
• Malformed Kafka records are isolated safely
• Event occurrence and processing timestamps support auditing

Future Improvements

• Confluent Cloud
• Schema Registry
• Authentication and authorization
• WebSockets or Server-Sent Events
• Testcontainers integration tests
• Prometheus and Grafana
• CI/CD deployment