Multi-Agent Banking System

For the full problem statement and system overview (architecture, diagrams, backlog), see docs/problem_statement+system_overview.md.

🚀 Endpoints

Service	Local (Docker)	Production (K8s)
Frontend	https://localhost/	https://ge42cer-devops-ss26.stud.k8s.aet.cit.tum.de/
Backend API	https://localhost/api	https://ge42cer-devops-ss26.stud.k8s.aet.cit.tum.de/api
Swagger UI	https://localhost/swagger-ui/index.html	https://ge42cer-devops-ss26.stud.k8s.aet.cit.tum.de/swagger-ui/index.html
OpenAPI JSON	https://localhost/v3/api-docs	https://ge42cer-devops-ss26.stud.k8s.aet.cit.tum.de/v3/api-docs
Grafana	https://localhost/grafana/	https://ge42cer-devops-ss26.stud.k8s.aet.cit.tum.de/grafana/
Prometheus	—	https://ge42cer-devops-ss26.stud.k8s.aet.cit.tum.de/prometheus/
Traefik Dashboard	http://localhost:8080/dashboard/	—

This repository contains a full mono-repo banking web application with:

• client: React + TypeScript frontend
• server: Java Spring Boot microservices (4 services, Gradle-built)
• genai: Python-based GenAI microservice
• infra: Docker Compose, Traefik reverse proxy, Kubernetes manifests, Helm chart, monitoring stack (Prometheus + Grafana)

---

Prerequisites & Requirements

Option 1: Docker-Based (Recommended)

Linux System Requirements:

# Install Docker
https://docs.docker.com/desktop/setup/install/linux/

Versions:

• Docker: 20.10+ (any recent version)
• Docker Compose: 2.0+
• Git: 2.0+

Option 2: Local Development (Full Stack)

Required Languages & Frameworks:

Component	Language	Framework	Version
Frontend	TypeScript	React + Vite	18.3.1 + 5.4.0
Backend Services	Java	Spring Boot (Gradle)	4.0.6
GenAI Service	Python	FastAPI	3.12
Database	SQL	PostgreSQL	16
Reverse Proxy	Go	Traefik	3.6

Linux System Packages:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y \
  build-essential \
  curl \
  git \
  openjdk-21-jdk \
  nodejs \
  npm \
  python3.12 \
  python3-pip \
  postgresql-client

Note: The project uses the Gradle wrapper (./gradlew) — no separate Gradle or Maven install needed.

Python Dependencies:

cd genai
pip install -r requirements.txt

Node.js Dependencies:

cd client
npm install

Pre-commit Hooks:

python3 -m pip install pre-commit
pre-commit install
pre-commit install --hook-type commit-msg
pre-commit run --all-files

This repository includes .pre-commit-config.yaml at the project root. Hooks cover:

• repository hygiene: whitespace, end-of-file, YAML syntax, merge conflicts
• formatting for Markdown, YAML, JSON, CSS, HTML, JS/TS via Prettier
• Python formatting for genai/ via Black and isort

Gradle & Dependency Management:

• Uses Gradle wrapper (./gradlew) — no pre-installed Gradle required
• Spring Boot dependencies resolved from Maven Central via the Gradle version catalog (server/gradle/libs.versions.toml)
• Java toolchain configured to JDK 21

1. System Architecture

Subsystems

• Traefik reverse proxy (config/traefik/) handles TLS termination, routing, and load balancing for all services.
• Frontend (client) renders dashboard and assistant UI.
• Orchestrator service (server/orchestrator-service) aggregates data from all backend services and exposes a unified API.
• Account service (server/account-service) manages account-level data and trend points.
• Transaction service (server/transaction-service) serves transactions and expense analytics.
• Banking service (server/banking-service) integrates with Enable Banking (PSD2/Open Banking) to link external bank accounts and sync balances and transactions into the shared schema. See ENABLE_BANKING_INTEGRATION.md.
• GenAI service (genai) provides summary and chat capabilities with local-first fallback.
• PostgreSQL stores persistent account and transaction data.

Required diagrams

• Subsystem decomposition: docs/uml/subsystem-decomposition.puml
• Use case diagram: docs/uml/use-case.puml
• Analysis object model: docs/uml/analysis-object-model.puml

2. Running Locally (Docker Compose)

Prerequisites:

• Docker + Docker Compose plugin

Create or update your local environment file:

# if .env already exists, just edit it
# otherwise create it
touch .env

Start with the team launcher (enforces required env file and variables):

./scripts/dev-up.sh

Optional: pass a custom env file path.

./scripts/dev-up.sh path/to/file.env

Stop the stack:

./scripts/dev-down.sh

See Endpoints at the top of this README for all app URLs.

3. GenAI Model Modes (No Cloud Dependency)

Configure in docker-compose.yml through env vars:

• MODEL_PROVIDER=local (default, no cloud dependency)
• MODEL_PROVIDER=ollama for local LLM via Ollama

4. CI/CD

GitHub Actions workflows:

• CI (.github/workflows/ci.yml):
  • Runs the full quality gate for backend via ./gradlew clean check (compilation + Error Prone + Spotless + SpotBugs + Detekt + tests)
  • Lints, tests, and builds the React frontend (npm run lint, npm run test, npm run build)
  • Tests the Python GenAI service (pytest)
  • Runs OWASP Dependency Check for vulnerability scanning
  • Uses Java 21 (Temurin), Node 22, Python 3.12
  • Uploads test reports and OWASP security reports as artifacts
• CD (.github/workflows/cd.yml):
  • Runs helm upgrade --install on merge to main (triggers after GHCR image build)
  • Can also be triggered manually via workflow_dispatch
  • Requires secrets: KUBECONFIG, TUMID, POSTGRES_PASSWORD

5. Kubernetes Deployment (Helm)

The Helm chart is in infra/helm/banking-app.

Deploy manually:

helm upgrade --install banking-app ./infra/helm/banking-app \
  --namespace ge42cer-devops26 --create-namespace \
  --set tumid=ge42cer \
  --set postgres.database.password=<secure-password> \
  --timeout 5m --wait

Disable monitoring if not needed:

helm upgrade --install banking-app ./infra/helm/banking-app \
  --namespace ge42cer-devops26 --create-namespace \
  --set tumid=ge42cer \
  --set postgres.database.password=<secure-password> \
  --set monitoring.prometheus.enabled=false \
  --set monitoring.grafana.enabled=false \
  --timeout 5m --wait

Kustomize manifests (legacy) are in infra/k8s/base.

Images are pulled from GitHub Container Registry (ghcr.io/aet-devops26/...).

6. Monitoring and Alerting

• Prometheus config: infra/monitoring/prometheus.yml
• Grafana dashboard JSON: infra/monitoring/grafana/dashboards/banking-overview.json
• Alert rule file: infra/monitoring/alerts.yml

Tracked metrics include:

• Request count
• Request latency (P95)
• Error rate (5xx)

7. API Documentation

• OpenAPI definition: server/openapi.yaml
• Swagger UI (runtime): http://localhost:8083/swagger-ui/index.html

8. Testing

• Java unit tests in each Spring service under src/test
• Python tests in genai/tests
• React tests in client/src/App.test.tsx

Manual local test commands (without Docker):

# All Java services (Gradle)
cd server && ./gradlew test

# Individual services
cd server && ./gradlew :account-service:test
cd server && ./gradlew :transaction-service:test
cd server && ./gradlew :orchestrator-service:test

# Python
cd genai && pip install -r requirements.txt && pytest

# React
cd client && npm install && npm run test