How aet-devops26/team-99-downtime works
1. Overall shape
This is a monorepo for a personal-finance system made of one React client, four backend services, a shared JVM library, and several deployment layers. The runtime architecture is microservice-based: user-facing UI, domain services, an auth service, and a Python GenAI helper service.
2. Client application boundary
apps/client is the browser frontend, built with React and Vite. It owns the navigation shell, protected/guest route layouts, and feature modules for auth, budgets, transactions, notifications, and dashboard views. It does not talk to backend services directly with handwritten HTTP calls; it uses generated TypeScript API clients under src/shared/api/generated.
3. Contract-first API flow
The frontend’s service clients are generated from the OpenAPI specs in /openapi. That makes the OpenAPI documents a key architectural boundary: backend service contracts are published first, then consumed by the client. The repo also includes tooling in tools/openapi to regenerate those clients.
4. Authentication subsystem
apps/auth-service is a separate TypeScript service for identity/session management. The client has dedicated auth hooks and forms around it, and route guards depend on session state. In the JVM services, shared security behavior comes from apps/commons-jvm, which provides common Spring Security/OpenAPI auto-configuration and a WhoAmIController for identity checks.
5. Transaction service responsibilities
apps/transaction-service owns expense records and transaction-oriented workflows: CRUD, free-text expense creation, CSV/file import, and error handling for malformed input or ambiguous descriptions. It depends on two other services through client classes: the GenAI service for categorization assistance and the Budget service for category/threshold-related checks.
6. Budget service responsibilities
apps/budget-service manages budget categories, budget status, threshold flags, and threshold-check orchestration. It exposes controllers for category management, budget status, and threshold checks. It also calls out to the transaction service to compute spend data and to the notification service to emit alerts when thresholds are crossed.
7. Notification subsystem
apps/notification-service is the persistence and delivery layer for alerts. It stores notification records and exposes a notification stream service, which suggests live push updates to the client rather than only polling. This service sits at the end of the alert pipeline: budget/transaction events create notifications, and the frontend reads them through the notification API and stream.
8. GenAI helper service
apps/genai-service is a Python service that isolates AI-assisted categorization logic and file parsing support. It is intentionally separated from the Java services so that experimental or heavyweight inference logic stays out of the core domain services. The transaction service is the main upstream consumer.
9. Data and persistence model
The services use repositories at the service boundary, and the deployment files show a shared PostgreSQL infrastructure with separate databases initialized per service. So the physical database is centralized, but the logical persistence boundary is still per service. That matters for the diagram: each domain service owns its schema/data access path, even if the same Postgres instance hosts them.
10. Deployment and edge delivery
The repo supports multiple deployment targets: local Docker Compose, Kubernetes/Helm, and an Azure VM path via Terraform + Ansible. In local/VM setups, Caddy is the edge proxy; in Kubernetes, ingress takes that role. The Helm chart also includes admin/support components like Swagger UI and Drizzle Studio, which are operational surfaces rather than core business services.
11. Build and execution model
The backend is polyglot: Spring Boot/Gradle for the Java services, Node/TypeScript for auth and the client, and Python/uv for GenAI. The monorepo is coordinated with Nx, with CI/CD in GitHub Actions and per-service Dockerfiles. For an architecture diagram, the important point is that service boundaries align with separate runtimes and separate deployables.
Main entry points: transaction-service Transaction Service · client Client · budget-service Budget Service · postgres Postgres
Components 17
Frontend
Browser app and shared client-side code
Services
Backend runtime services and shared JVM support
- Auth Service · Identity and session management service
apps/auth-service - Transaction Service · Expense records, free-text creation, CSV/file import, and transaction workflows
apps/transaction-service - Budget Service · Budget categories, budget status, and threshold-check orchestration
apps/budget-service - Notification Service · Alert persistence and notification stream delivery
apps/notification-service - GenAI Service · AI-assisted categorization and file parsing helper
apps/genai-service - Commons JVM · Shared security and OpenAPI auto-configuration plus identity helper controller
apps/commons-jvm
Contracts
API specs and client generation
- OpenAPI Specs · Service API contracts published for client generation
openapi - API Generator · Regenerates client SDKs from OpenAPI definitions
tools/openapi
Platform
Deployment and infrastructure layers
- Compose · Local multi-service container composition
docker-compose.yaml - Helm Stack · Kubernetes manifests and Helm chart for app, ingress, database, and support components
k8s/helm/t99-app - Terraform · Cloud infrastructure provisioning path
infra/terraform - Ansible · VM application and edge-proxy configuration path
infra/ansible - Postgres · Central PostgreSQL infrastructure with per-service logical databases
infra/postgres - Edge Proxy · Traffic entry point for local and VM setups, ingress role in Kubernetes
Caddyfile - Ops UIs · Swagger UI and Drizzle Studio operational access surfaces
k8s/helm/t99-app/templates/swagger-ui
Connections 29
- Client → Gen API: uses · Frontend calls backend through generated SDKs
- Gen API → OpenAPI Specs: generated from · TypeScript clients are derived from service contracts
- API Generator → OpenAPI Specs: reads · Tooling regenerates clients from OpenAPI documents
- API Generator → Gen API: writes · Regeneration target for client SDKs
- Client → Auth Service: auth · Login, signup, and session state depend on the auth service
- Client → Transaction Service: transactions · Transaction features are backed by the transaction API
- Client → Budget Service: budgets · Budget views and management use the budget API
- Client → Notification Service: notifications · Notification feed and stream consume the notification API
- Auth Service → Commons JVM: shares · Runtime security/OpenAPI behavior is centralized in the JVM common library
- Transaction Service → Commons JVM: shares · Java service reuses shared security and OpenAPI config
- Budget Service → Commons JVM: shares · Java service reuses shared security and OpenAPI config
- Notification Service → Commons JVM: shares · Java service reuses shared security and OpenAPI config
- Transaction Service → GenAI Service: calls · Transaction workflows delegate categorization and parsing assistance
- Transaction Service → Budget Service: calls · Transaction workflows consult budget/category checks
- Budget Service → Transaction Service: queries · Budget status and threshold checks need transaction spend data
- Budget Service → Notification Service: alerts · Threshold crossings create notifications
- Transaction Service → Notification Service: emits · Transaction events can surface as alerts
- Auth Service → Postgres: stores · Service data persists in the shared Postgres platform
- Transaction Service → Postgres: stores · Transaction data persists in the shared Postgres platform
- Budget Service → Postgres: stores · Budget and threshold data persist in the shared Postgres platform
- Notification Service → Postgres: stores · Notification records persist in the shared Postgres platform
- Client → Edge Proxy: enters via · Browser traffic reaches the system through the edge proxy or ingress
- Compose → Edge Proxy: routes through · Local compose deployment uses Caddy as the edge proxy
- Helm Stack → Edge Proxy: routes through · Kubernetes deployment uses ingress as the edge entry point
- Ansible → Edge Proxy: configures · VM path templates and configures the proxy
- Terraform → Postgres: provisions · Cloud infrastructure includes the database layer
- Terraform → Ansible: hands off to · Terraform bootstraps VM infrastructure that Ansible configures
- Helm Stack → Ops UIs: includes · Helm chart deploys operational support surfaces
- Helm Stack → Postgres: deploys · Helm chart includes the shared Postgres instance and init scripts