Billing Platform

A production-grade billing platform built with Java 17 + Spring Boot 3.2, React + TypeScript, fully containerized with Docker Compose. It enables organizations to manage teams, projects, and tasks while providing secure authentication, event-driven processing, subscription billing, notifications, and scalable infrastructure.

Architecture

┌──────────────────────────────────────────────────────────┐
│                    Nginx (Port 80)                        │
│          API Gateway + Load Balancer + Rate Limiter       │
└───────────────────┬──────────────────┬───────────────────┘
                    │                  │
          ┌─────────▼─────┐   ┌───────▼──────┐
          │  Frontend      │   │  Backend x2  │
          │  React + TS    │   │  Spring Boot │
          │  TailwindCSS   │   │  Port 8080   │
          └───────────────┘   └──────┬───────┘
                                     │
              ┌──────────────────────┼──────────────────────┐
              │                      │                      │
     ┌────────▼───────┐   ┌─────────▼───────┐   ┌─────────▼──────┐
     │  PostgreSQL     │   │   MongoDB        │   │   Redis         │
     │  Primary DB     │   │  Audit Logs      │   │  Cache/Tokens   │
     └────────────────┘   └─────────────────┘   └────────────────┘
              │
     ┌────────▼───────┐   ┌────────────────┐   ┌────────────────┐
     │  Kafka          │   │  MinIO (S3)    │   │  Prometheus +  │
     │  Event Bus      │   │  File Storage  │   │  Grafana       │
     └────────────────┘   └────────────────┘   └────────────────┘

Domain Modules (Modular Monolith)

Module	Description
auth	JWT authentication, refresh tokens, password reset
users	User profiles, avatar upload, preferences
organizations	Multi-tenant orgs, members, roles
billing	Stripe subscriptions, payments, invoices, webhooks
projects	Project management per organization
tasks	Task kanban board with assignments
notifications	In-app + email notifications via Kafka
audit	MongoDB audit log for all important actions
shared	Cross-cutting: security, exceptions, messaging

Quick Start

Prerequisites

• Docker Desktop 4.x+
• Docker Compose 2.x+

1. Clone and configure

git clone <repo>
cd saas-billing-platform

cp backend/.env.example backend/.env
# Edit backend/.env with your Stripe and SendGrid API keys

2. Start all services

docker-compose up -d

3. Access the platform

Service	URL
Frontend	http://localhost
API	http://localhost/api
Swagger UI	http://localhost/api/swagger-ui.html
Grafana	http://localhost:3001 (admin/grafana_pass_2024)
Prometheus	http://localhost:9090
Kafka UI	http://localhost:8090
MinIO Console	http://localhost:9001

Default admin credentials

• Email: admin@saas-billing.com
• Password: Admin@123456

Technology Stack

Backend

• Java 17 + Spring Boot 3.2.3
• Architecture: Modular Monolith, Clean Architecture, DDD, SOLID
• Security: Spring Security, JWT (JJWT), BCrypt, Redis session
• Database: PostgreSQL 16 + Flyway migrations
• Audit: MongoDB 7 (flexible document storage)
• Cache: Redis 7 (tokens, read-through, rate limiting)
• Messaging: Apache Kafka (event-driven, transactional outbox)
• Resilience: Resilience4j (circuit breaker, retry, rate limiter, bulkhead)
• Payments: Stripe Java SDK (subscriptions, webhooks, invoices)
• Email: SendGrid (verification, password reset, invoices)
• Storage: MinIO / AWS S3 SDK (avatars, attachments)
• Observability: Micrometer + Prometheus + Grafana

Frontend

• React 18 + TypeScript
• Styling: TailwindCSS + custom design system
• State: Zustand (auth) + React Query (server state)
• Forms: React Hook Form + Zod validation
• Charts: Recharts
• Routing: React Router v6

Infrastructure

• API Gateway: Nginx (routing, load balancing, rate limiting)
• Container: Docker Compose (11 services)
• Monitoring: Prometheus + Grafana dashboards

API Endpoints

Authentication

POST /api/auth/register         Register new user
POST /api/auth/login            Login
POST /api/auth/refresh          Refresh access token
POST /api/auth/logout           Logout
GET  /api/auth/verify-email     Verify email address
POST /api/auth/forgot-password  Request password reset
POST /api/auth/reset-password   Reset password

Organizations

POST   /api/organizations                      Create organization
GET    /api/organizations                      List user's organizations
GET    /api/organizations/{id}                 Get organization
PATCH  /api/organizations/{id}                 Update organization
GET    /api/organizations/{id}/members         List members (paginated)
POST   /api/organizations/{id}/members/invite  Invite member
DELETE /api/organizations/{id}/members/{uid}   Remove member

Billing

GET  /api/billing/plans                                    List public plans
POST /api/billing/organizations/{id}/checkout              Create Stripe checkout
GET  /api/billing/organizations/{id}/subscription          Get subscription
POST /api/billing/organizations/{id}/subscription/cancel   Cancel subscription
POST /api/billing/organizations/{id}/subscription/upgrade  Change plan
GET  /api/billing/organizations/{id}/invoices              List invoices
GET  /api/billing/organizations/{id}/payments              List payments
POST /api/billing/webhooks/stripe                          Stripe webhook

Projects & Tasks

POST   /api/organizations/{id}/projects   Create project
GET    /api/organizations/{id}/projects   List projects
GET    /api/projects/{id}                 Get project
PATCH  /api/projects/{id}                 Update project
DELETE /api/projects/{id}                 Delete project
POST   /api/projects/{id}/tasks           Create task
GET    /api/projects/{id}/tasks           List tasks
GET    /api/tasks/{id}                    Get task
PATCH  /api/tasks/{id}                    Update task
DELETE /api/tasks/{id}                    Delete task

Kafka Topics

Topic	Events
saas.user.events	UserRegistered, UserLoggedIn
saas.billing.events	PaymentSucceeded, PaymentFailed, SubscriptionCreated
saas.project.events	ProjectCreated
saas.task.events	TaskCreated, TaskCompleted
saas.notification.events	NotificationCreated
saas.audit.events	All auditable actions
saas.email.events	Email send requests
saas.analytics.events	Analytics data

Security

• Stateless JWT (15 min access / 7 day refresh with rotation)
• Refresh tokens stored in Redis with automatic expiry
• Access token blacklist on logout
• BCrypt password hashing (cost 12)
• Account lockout after 5 failed login attempts
• Rate limiting via Nginx (auth: 10 req/min, API: 100 req/min)
• RBAC: SUPER_ADMIN, ORG_ADMIN, MEMBER
• Stripe webhook signature verification
• Transactional outbox pattern for reliable event delivery

Development

# Backend only (with local infra)
cd backend
mvn spring-boot:run -Dspring-boot.run.profiles=local

# Frontend only
cd frontend
npm install && npm run dev

# Run all infra services (no app)
docker-compose up -d postgres mongodb redis kafka minio