# aet-devops26/team-99-downtime architecture

> Architecture diagram of the GitHub repository aet-devops26/team-99-downtime, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aet-devops26/team-99-downtime
- Repository: https://github.com/aet-devops26/team-99-downtime

## Overview

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: [`apps/transaction-service`](https://github.com/aet-devops26/team-99-downtime/tree/main/apps/transaction-service) (Transaction Service), [`apps/client`](https://github.com/aet-devops26/team-99-downtime/tree/main/apps/client) (Client), [`apps/budget-service`](https://github.com/aet-devops26/team-99-downtime/tree/main/apps/budget-service) (Budget Service), [`infra/postgres`](https://github.com/aet-devops26/team-99-downtime/tree/main/infra/postgres) (Postgres)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_client["Client<br/>React/Vite app"]
  node_client_api["Gen API<br/>generated TS clients"]
end

subgraph group_services["Services"]
  node_auth_service["Auth Service"]
  node_transaction_service["Transaction Service<br/>Spring Boot service"]
  node_budget_service["Budget Service<br/>Spring Boot service"]
  node_notification_service["Notification Service<br/>Spring Boot service"]
  node_genai_service["GenAI Service<br/>Python service"]
  node_commons_jvm["Commons JVM<br/>shared Spring lib"]
end

subgraph group_contracts["Contracts"]
  node_openapi_specs["OpenAPI Specs<br/>contract docs"]
  node_openapi_tools["API Generator<br/>tooling"]
end

subgraph group_platform["Platform"]
  node_docker_compose["Compose<br/>local runtime"]
  node_k8s_helm["Helm Stack<br/>kubernetes deploy"]
  node_terraform["Terraform<br/>azure infra"]
  node_ansible["Ansible<br/>vm config"]
  node_postgres[("Postgres<br/>shared database")]
  node_caddy_ingress{{"Edge Proxy<br/>Caddy/Ingress"}}
  node_swagger_studio["Ops UIs<br/>support services"]
end

node_client -->|"uses"| node_client_api
node_client_api -->|"generated from"| node_openapi_specs
node_openapi_tools -->|"reads"| node_openapi_specs
node_openapi_tools -->|"writes"| node_client_api
node_client -->|"auth"| node_auth_service
node_client -->|"transactions"| node_transaction_service
node_client -->|"budgets"| node_budget_service
node_client -->|"notifications"| node_notification_service
node_auth_service -->|"shares"| node_commons_jvm
node_transaction_service -->|"shares"| node_commons_jvm
node_budget_service -->|"shares"| node_commons_jvm
node_notification_service -->|"shares"| node_commons_jvm
node_transaction_service -->|"calls"| node_genai_service
node_transaction_service -->|"calls"| node_budget_service
node_budget_service -->|"queries"| node_transaction_service
node_budget_service -->|"alerts"| node_notification_service
node_transaction_service -->|"emits"| node_notification_service
node_auth_service -->|"stores"| node_postgres
node_transaction_service -->|"stores"| node_postgres
node_budget_service -->|"stores"| node_postgres
node_notification_service -->|"stores"| node_postgres
node_client -->|"enters via"| node_caddy_ingress
node_docker_compose -->|"routes through"| node_caddy_ingress
node_k8s_helm -->|"routes through"| node_caddy_ingress
node_ansible -->|"configures"| node_caddy_ingress
node_terraform -->|"provisions"| node_postgres
node_terraform -->|"hands off to"| node_ansible
node_k8s_helm -->|"includes"| node_swagger_studio
node_k8s_helm -->|"deploys"| node_postgres

click node_client "https://github.com/aet-devops26/team-99-downtime/tree/main/apps/client"
click node_client_api "https://github.com/aet-devops26/team-99-downtime/tree/main/apps/client/src/shared/api/generated"
click node_auth_service "https://github.com/aet-devops26/team-99-downtime/tree/main/apps/auth-service"
click node_transaction_service "https://github.com/aet-devops26/team-99-downtime/tree/main/apps/transaction-service"
click node_budget_service "https://github.com/aet-devops26/team-99-downtime/tree/main/apps/budget-service"
click node_notification_service "https://github.com/aet-devops26/team-99-downtime/tree/main/apps/notification-service"
click node_genai_service "https://github.com/aet-devops26/team-99-downtime/tree/main/apps/genai-service"
click node_commons_jvm "https://github.com/aet-devops26/team-99-downtime/tree/main/apps/commons-jvm"
click node_openapi_specs "https://github.com/aet-devops26/team-99-downtime/tree/main/openapi"
click node_openapi_tools "https://github.com/aet-devops26/team-99-downtime/tree/main/tools/openapi"
click node_docker_compose "https://github.com/aet-devops26/team-99-downtime/blob/main/docker-compose.yaml"
click node_k8s_helm "https://github.com/aet-devops26/team-99-downtime/tree/main/k8s/helm/t99-app"
click node_terraform "https://github.com/aet-devops26/team-99-downtime/tree/main/infra/terraform"
click node_ansible "https://github.com/aet-devops26/team-99-downtime/tree/main/infra/ansible"
click node_postgres "https://github.com/aet-devops26/team-99-downtime/tree/main/infra/postgres"
click node_caddy_ingress "https://github.com/aet-devops26/team-99-downtime/tree/main/Caddyfile"
click node_swagger_studio "https://github.com/aet-devops26/team-99-downtime/tree/main/k8s/helm/t99-app/templates/swagger-ui"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_client_api toneBlue
class node_auth_service,node_transaction_service,node_budget_service,node_notification_service,node_genai_service,node_commons_jvm toneAmber
class node_openapi_specs,node_openapi_tools toneMint
class node_docker_compose,node_k8s_helm,node_terraform,node_ansible,node_postgres,node_caddy_ingress,node_swagger_studio toneRose
```

## Components

### Frontend

Browser app and shared client-side code

- [Client](https://github.com/aet-devops26/team-99-downtime/tree/main/apps/client): React/Vite app · Browser UI with route layouts and feature modules for auth, budgets, transactions, notifications, and dashboard · `apps/client`
- [Gen API](https://github.com/aet-devops26/team-99-downtime/tree/main/apps/client/src/shared/api/generated): generated TS clients · Generated TypeScript service clients consumed by the React app · `apps/client/src/shared/api/generated`

### Services

Backend runtime services and shared JVM support

- [Auth Service](https://github.com/aet-devops26/team-99-downtime/tree/main/apps/auth-service): Node auth service · Identity and session management service · `apps/auth-service`
- [Transaction Service](https://github.com/aet-devops26/team-99-downtime/tree/main/apps/transaction-service): Spring Boot service · Expense records, free-text creation, CSV/file import, and transaction workflows · `apps/transaction-service`
- [Budget Service](https://github.com/aet-devops26/team-99-downtime/tree/main/apps/budget-service): Spring Boot service · Budget categories, budget status, and threshold-check orchestration · `apps/budget-service`
- [Notification Service](https://github.com/aet-devops26/team-99-downtime/tree/main/apps/notification-service): Spring Boot service · Alert persistence and notification stream delivery · `apps/notification-service`
- [GenAI Service](https://github.com/aet-devops26/team-99-downtime/tree/main/apps/genai-service): Python service · AI-assisted categorization and file parsing helper · `apps/genai-service`
- [Commons JVM](https://github.com/aet-devops26/team-99-downtime/tree/main/apps/commons-jvm): shared Spring lib · Shared security and OpenAPI auto-configuration plus identity helper controller · `apps/commons-jvm`

### Contracts

API specs and client generation

- [OpenAPI Specs](https://github.com/aet-devops26/team-99-downtime/tree/main/openapi): contract docs · Service API contracts published for client generation · `openapi`
- [API Generator](https://github.com/aet-devops26/team-99-downtime/tree/main/tools/openapi): tooling · Regenerates client SDKs from OpenAPI definitions · `tools/openapi`

### Platform

Deployment and infrastructure layers

- [Compose](https://github.com/aet-devops26/team-99-downtime/blob/main/docker-compose.yaml): local runtime · Local multi-service container composition · `docker-compose.yaml`
- [Helm Stack](https://github.com/aet-devops26/team-99-downtime/tree/main/k8s/helm/t99-app): kubernetes deploy · Kubernetes manifests and Helm chart for app, ingress, database, and support components · `k8s/helm/t99-app`
- [Terraform](https://github.com/aet-devops26/team-99-downtime/tree/main/infra/terraform): azure infra · Cloud infrastructure provisioning path · `infra/terraform`
- [Ansible](https://github.com/aet-devops26/team-99-downtime/tree/main/infra/ansible): vm config · VM application and edge-proxy configuration path · `infra/ansible`
- [Postgres](https://github.com/aet-devops26/team-99-downtime/tree/main/infra/postgres): shared database · Central PostgreSQL infrastructure with per-service logical databases · `infra/postgres`
- [Edge Proxy](https://github.com/aet-devops26/team-99-downtime/tree/main/Caddyfile): Caddy/Ingress · Traffic entry point for local and VM setups, ingress role in Kubernetes · `Caddyfile`
- [Ops UIs](https://github.com/aet-devops26/team-99-downtime/tree/main/k8s/helm/t99-app/templates/swagger-ui): support services · Swagger UI and Drizzle Studio operational access surfaces · `k8s/helm/t99-app/templates/swagger-ui`

## Connections

- 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
