Project Prometheus — Banking Platform

Production-grade fintech platform built with hexagonal architecture, event sourcing, and Kubernetes-first development workflow.

⚠️ Not production-ready: This is a learning/portfolio platform. It is not security-audited and must not be used to process real money.

---

Quickstart

Option A: K3s in WSL2 + Tilt (Recommended on Windows)

1. Start PowerShell as Administrator
2. Connect to K3s:

   .\scripts\k3s-connect.ps1

3. Start backend:

   tilt up --stream=true

4. Start dashboard (separate terminal):

   cd dashboard
   Copy-Item .env.example .env
   npm install
   npm run dev

Option B: Local k3d Cluster

.\infrastructure\local\setup-local.ps1
tilt up --stream=true

Environment Setup

• Copy dashboard/.env.example to dashboard/.env and configure values
• Never commit .env files

---

Technology Stack

Backend

• Java 21 (Virtual Threads)
• Spring Boot 3.2+
• PostgreSQL 16 (Event Store)
• Redis (Caching)
• Kafka (Event Streaming)

Infrastructure

• K3s / k3d (Kubernetes)
• Linkerd (Service Mesh)
• nginx-ingress (Ingress Controller)
• Grafana Alloy (Observability)
• Tilt (Development)

Frontend

• React + TypeScript
• Vite

---

Architecture

Hexagonal Architecture (Ports & Adapters) with:

• Domain Layer: Pure Java, zero framework dependencies
• Application Layer: Use cases, command/query handlers
• Infrastructure Layer: Database, messaging, external APIs

Event Sourcing for ledger/account state with CQRS read models.

See docs/ARCHITECTURE.md for detailed explanations.

---

Project Structure

prometheus/
├── services/
│   └── account-service/
│       └── src/main/java/com/prometheus/account/
│           ├── api/              # REST controllers
│           ├── application/      # Use cases, handlers
│           ├── domain/           # Business logic (pure Java)
│           │   ├── model/        # Aggregates, Entities, Value Objects
│           │   ├── event/        # Domain Events
│           │   └── service/      # Domain Services
│           └── infrastructure/   # DB, Redis, Kafka adapters
│
├── dashboard/                    # React frontend
│
├── k8s/
│   ├── base/                     # Shared Kubernetes manifests
│   └── overlays/
│       ├── local/                # Local overrides
│       └── prod/                 # Production overrides
│
├── infrastructure/
│   ├── local/                    # k3d cluster config
│   ├── linkerd/                  # Service mesh
│   ├── nginx-ingress/            # Ingress controller
│   └── grafana-alloy/            # Observability
│
└── scripts/                      # Utility scripts

---

Development

Prerequisites

• Docker Desktop (8GB+ RAM)
• kubectl, helm, tilt
• Node.js (for dashboard)
• WSL2 + K3s OR k3d

Common Endpoints

• Tilt UI: http://localhost:10350
• Dashboard: http://localhost:5173 (Vite default)
• API: http://localhost:8082/api/v1

Running Tests

# Backend (from service directory)
./gradlew test

# Frontend (from dashboard directory)
npm test

---

Documentation

• Architecture & Design Decisions - Detailed rationale for architectural choices
• Implementation Plan - Phase 1 roadmap
• Phase 2 Plan - Core Banking & Payments
• User Flows - Application user flows
• Core Domain Guide - Domain model explanation

---

Contributing

1. Create a feature branch
2. Make changes following existing patterns
3. Ensure tests pass
4. Submit a pull request

---

License

Licensed under the Apache License 2.0. See LICENSE.