Budget Analyzer Orchestration

"Archetype: coordinator. Role: System orchestrator; coordinates cross-cutting concerns and deployment."

— AGENTS.md

Architecture Boundaries

This project demonstrates production-grade patterns:

• Authentication: OAuth2/OIDC with Auth0, session-based edge authorization, session management
• API Gateway: Session validation (ext_authz), auth-path throttling at Istio ingress, API routing and API-path throttling at NGINX
• Microservices: Spring Boot, Kubernetes, Tilt local development

Live Development in Kubernetes

Edit code locally. Changes reach the running Kubernetes pod in seconds — without image rebuilds or pod restarts — while the full production stack (Istio mTLS, network policies, ext_authz, TLS infrastructure) stays active.

• Java services: Gradle compiles on the host, Tilt syncs the JAR into the pod and restarts the process
• React frontend: Tilt syncs source files, Vite HMR hot-patches the browser (sub-second)
• Shared library: Changes to service-common automatically cascade to all downstream services

This avoids the usual tradeoff between fast local development and production-faithful Kubernetes environments. See Live Development Pipeline for details.

Quick Start

Getting Started owns the supported local startup checklist. It is the only setup doc that should be treated as the happy-path ./setup.sh and tilt up flow.

For deeper detail, use the owner docs directly:

• Local Environment Mechanics - live update, mixed local-and-cluster workflows, and environment internals
• Service-Common Artifact Resolution
  • local credential-free artifact flow versus GitHub Packages
• Tilt/Kind Manual Deep Dive - manual bootstrap internals only; not the default onboarding path
• Scripts Directory - verifier catalog and operational entry points

Common operator entry points after the stack is healthy:

• app: https://app.budgetanalyzer.localhost
• Tilt UI: http://localhost:10350
• unified API docs: https://app.budgetanalyzer.localhost/api-docs
• observability helper: ./scripts/ops/start-observability-port-forwards.sh

Exact /api-docs behavior lives in docs-aggregator/README.md. Exact observability access commands and operator posture live in Observability Architecture.

Documentation

• Documentation Ownership
• Getting Started
• Local Environment Mechanics
• Tilt/Kind Manual Deep Dive
• Architecture Overview
• Observability Architecture
• Development Guide

Service Repositories

• service-common - Shared library
• transaction-service - Transaction API
• currency-service - Currency API
• budget-analyzer-web - React frontend
• session-gateway - OAuth2 authentication and session management

License

MIT