# barryii/fincloud architecture

> Architecture diagram of the GitHub repository barryii/fincloud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/barryii/fincloud
- Repository: https://github.com/barryii/fincloud

## Overview

1. **Repository shape**
   - This repo contains three related codebases with different maturity:
     - **`Main/`** is the production FinOps platform.
     - **`Barry/`** is an earlier prototype with its own backend/frontend and Kubernetes stack.
     - **`Key/`** is an AWS-focused integration experiment.
   - For an architecture diagram, center the **Main** system and treat Barry/Key as adjacent or historical subsystems.

2. **Main is a two-tier product**
   - `Main/api/` is a **FastAPI** backend.
   - `Main/frontend/` is a **React + Vite** SPA.
   - The frontend talks to the backend over HTTP via `Main/frontend/src/services/api.ts`, and the backend exposes feature-specific API modules rather than a single monolith route file.

3. **Main backend structure**
   - The backend is organized by domain under `Main/api/`:
     - `auth.py`
     - `connections.py`
     - `dashboard.py`
     - `budgets_api.py`
     - `metrics_api.py`
     - `resources_api.py`
     - `recommendations_api.py`
     - `anomalies` detection
     - `export_api.py`
     - `sync_api.py`
     - plus error handlers for AWS/GCP-specific failures.
   - `main.py` is the app entrypoint; `config.py` and `database.py` provide shared infrastructure wiring.

4. **Main frontend structure**
   - The frontend is a multi-page dashboard with feature pages for:
     - landing/login/connect flows
     - dashboard, metrics, cost trends, resources
     - budgets, anomalies, reports, optimization, notifications, billing settings
     - audit logs, account settings, password reset, email verification
   - Shared UI state is managed with React contexts such as `AccountContext`, `CurrencyContext`, and `DateRangeContext`, which indicate that many API calls are scoped by account, currency, and time window.

5. **Primary business flow: cloud account connection**
   - The main user journey is: **authenticate → connect cloud accounts → ingest billing/usage data → visualize and optimize spend**.
   - Connection setup is supported on both sides:
     - backend auth and setup-token logic
     - frontend connect pages and callback flows
   - The repo includes `gcp_setup_token.py`, `secrets.py`, and `scripts/gcp_setup.sh`, suggesting a staged onboarding path for GCP access.

6. **Primary business flow: data ingestion and sync**
   - The backend separates **provider sync** into dedicated modules:
     - `sync_aws.py`, `sync_aws_assets.py`, `sync_aws_metrics.py`
     - `sync_gcp.py`, `sync_gcp_assets.py`, `sync_gcp_metrics.py`
   - This indicates the system ingests both **cost/billing data** and **resource/asset metrics**, then normalizes them for downstream analytics.
   - The sync layer is a boundary between external cloud APIs and the internal analytics/data model.

7. **Analytics and decision-support features**
   - The backend includes distinct services for:
     - **dashboard summaries**
     - **trend metrics**
     - **resource inventory**
     - **budget management**
     - **recommendations/optimization**
     - **anomaly detection**
     - **reports/export**
   - The frontend mirrors these capabilities with charting and summary components, so the diagram should show a shared analytics core feeding multiple UI views.

8. **Persistence and domain model**
   - Main has a dedicated model layer under `Main/api/models` and shared schemas under `Main/api/schemas`.
   - The presence of `database.py`, audit/budget/metric/resource APIs, and migration-heavy history in sibling projects suggests a relational persistence layer with structured domain entities.
   - Key domain concepts visible in the repo are: **accounts, costs, resources, metrics, budgets, anomalies, recommendations, and notifications/audit logs**.

9. **External integrations and operational concerns**
   - The backend integrates with **AWS and GCP** directly; provider-specific modules and error handlers make that explicit.
   - There is also an `email_service.py`, so notification workflows likely leave the system via email.
   - `secrets.py` and setup-token modules suggest secure credential handling is a first-class boundary, not just a config detail.

10. **Deployment topology**
   - `Main/Dockerfile`, `Main/apprunner.yaml`, and frontend deployment assets indicate separate deployable units for backend and frontend.
   - `Main/scripts/` contains setup automation, while `Main/frontend/wrangler.toml` suggests a frontend deployment target separate from the API.
   - In the older `Barry/` codebase, deployment is more infrastructure-heavy: Kubernetes manifests for app, Postgres, Redis, Kong, and Keycloak, which shows an alternate architecture with explicit auth gateway and platform services.

11. **Barry prototype architecture**
   - Barry is a more infrastructure-complete prototype:
     - FastAPI backend under `Barry/app`
     - React frontend under `Barry/frontend`
     - Kubernetes manifests for **app, Postgres, Redis, Kong, and Keycloak**
   - It also has provider collectors under `Barry/app/services/azure` and `Barry/app/services/gcp`, plus SQL migrations, indicating a mature multi-cloud backend design with centralized auth and API gateway patterns.

12. **Key AWS-specific experiment**
   - `Key/` focuses on AWS cloud account onboarding and cost retrieval.
   - Backend modules include cloud-account APIs, AWS connection/cost services, encryption, and external-ID utilities.
   - Frontend is a Next.js app centered on AWS connection and cost dashboard flows, with CloudFormation support for IAM role setup.
   - This branch is best read as a reusable AWS onboarding pattern rather than the main product surface.

13. **How to draw the system**
   - A useful diagram would show:
     - **User browser → Main frontend**
     - **Main frontend → Main FastAPI backend**
     - **Main backend → internal database**
     - **Main backend → AWS/GCP APIs**
     - **Main backend → email service**
     - optionally **sync jobs** as backend-triggered ingestion processes
   - Then place **Barry** and **Key** off to the side as prototype/experimental branches with their own auth and deployment stacks.

Main entry points: [`Main/api`](https://github.com/barryii/fincloud/tree/main/Main/api) (Main backend), [`Main/frontend`](https://github.com/barryii/fincloud/tree/main/Main/frontend) (Main frontend), [`Main/api/auth.py`](https://github.com/barryii/fincloud/blob/main/Main/api/auth.py) (Auth & setup), [`Main/api/sync_api.py`](https://github.com/barryii/fincloud/blob/main/Main/api/sync_api.py) (Sync pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_main["Main platform"]
  node_main_fe["Main frontend<br/>React SPA"]
  node_main_ctx["Shared state<br/>React contexts"]
  node_main_api["Main backend<br/>FastAPI app"]
  node_main_auth["Auth & setup<br/>auth/onboarding<br/>[auth.py]"]
  node_main_sync["Sync pipeline<br/>ingestion jobs<br/>[sync_api.py]"]
  node_main_analytics["Analytics API<br/>domain services<br/>[dashboard.py]"]
  node_main_db[("Database<br/>relational store<br/>[database.py]")]
  node_main_models["Models & schemas<br/>domain model"]
  node_main_errors["Cloud errors<br/>provider handlers<br/>[aws_error.py]"]
  node_main_email["Email service<br/>notifications<br/>[email_service.py]"]
end

subgraph group_barry["Barry prototype"]
  node_barry_fe["Barry frontend<br/>React dashboard"]
  node_barry_api["Barry backend<br/>FastAPI app"]
  node_barry_platform{{"K8s stack<br/>platform"}}
end

subgraph group_key["Key experiment"]
  node_key_fe["Key frontend<br/>Next.js app"]
  node_key_api["Key backend<br/>FastAPI app"]
  node_key_aws{{"AWS services<br/>AWS integration"}}
  node_key_cf["CloudFormation<br/>infrastructure as code"]
end

subgraph group_external["External systems"]
  node_user(("User browser<br/>actor"))
  node_aws_api{{"AWS APIs<br/>external cloud"}}
  node_gcp_api{{"GCP APIs<br/>external cloud"}}
  node_mail_service{{"Email provider<br/>external service"}}
end

node_user -->|"uses"| node_main_fe
node_main_fe -->|"scoped by"| node_main_ctx
node_main_fe -->|"HTTP API"| node_main_api
node_main_api -->|"auth flows"| node_main_auth
node_main_api -->|"runs sync"| node_main_sync
node_main_api -->|"serves features"| node_main_analytics
node_main_api -->|"reads/writes"| node_main_db
node_main_api -->|"uses"| node_main_models
node_main_api -->|"handles"| node_main_errors
node_main_api -->|"sends"| node_main_email
node_main_auth -->|"connects"| node_aws_api
node_main_auth -->|"connects"| node_gcp_api
node_main_sync -->|"ingests"| node_aws_api
node_main_sync -->|"ingests"| node_gcp_api
node_main_email -->|"delivers via"| node_mail_service
node_barry_fe -->|"HTTP API"| node_barry_api
node_barry_api -->|"deployed with"| node_barry_platform
node_barry_api -.->|"persists similar domain"| node_main_db
node_key_fe -->|"HTTP API"| node_key_api
node_key_api -->|"uses"| node_key_aws
node_key_fe -->|"provisions"| node_key_cf
node_key_api -.->|"expects"| node_key_cf

click node_main_fe "https://github.com/barryii/fincloud/tree/main/Main/frontend"
click node_main_ctx "https://github.com/barryii/fincloud/tree/main/Main/frontend/src/context"
click node_main_api "https://github.com/barryii/fincloud/tree/main/Main/api"
click node_main_auth "https://github.com/barryii/fincloud/blob/main/Main/api/auth.py"
click node_main_sync "https://github.com/barryii/fincloud/blob/main/Main/api/sync_api.py"
click node_main_analytics "https://github.com/barryii/fincloud/blob/main/Main/api/dashboard.py"
click node_main_db "https://github.com/barryii/fincloud/blob/main/Main/api/database.py"
click node_main_errors "https://github.com/barryii/fincloud/blob/main/Main/api/aws_error.py"
click node_main_email "https://github.com/barryii/fincloud/blob/main/Main/api/email_service.py"
click node_barry_fe "https://github.com/barryii/fincloud/tree/main/Barry/frontend"
click node_barry_api "https://github.com/barryii/fincloud/tree/main/Barry/app"
click node_barry_platform "https://github.com/barryii/fincloud/tree/main/Barry/k8s"
click node_key_fe "https://github.com/barryii/fincloud/tree/main/Key/frontend"
click node_key_api "https://github.com/barryii/fincloud/tree/main/Key/backend"
click node_key_aws "https://github.com/barryii/fincloud/tree/main/Key/backend/app/services/aws"
click node_key_cf "https://github.com/barryii/fincloud/blob/main/Key/cloudformation/finops-iam-role.yaml"

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_main_fe,node_main_ctx,node_main_api,node_main_auth,node_main_sync,node_main_analytics,node_main_db,node_main_models,node_main_errors,node_main_email toneBlue
class node_barry_fe,node_barry_api,node_barry_platform toneAmber
class node_key_fe,node_key_api,node_key_aws,node_key_cf toneMint
class node_user,node_aws_api,node_gcp_api,node_mail_service toneRose
```

## Components

### Main platform

Production FinOps product

- [Main frontend](https://github.com/barryii/fincloud/tree/main/Main/frontend): React SPA · Multi-page dashboard and onboarding UI · `Main/frontend`
- [Shared state](https://github.com/barryii/fincloud/tree/main/Main/frontend/src/context): React contexts · Account, currency, and date-range UI scope · `Main/frontend/src/context`
- [Main backend](https://github.com/barryii/fincloud/tree/main/Main/api): FastAPI app · Production API entrypoint and shared wiring · `Main/api`
- [Auth & setup](https://github.com/barryii/fincloud/blob/main/Main/api/auth.py): auth/onboarding · Login, connections, setup tokens, and secrets · `Main/api/auth.py`
- [Sync pipeline](https://github.com/barryii/fincloud/blob/main/Main/api/sync_api.py): ingestion jobs · AWS/GCP sync orchestration and provider-specific loaders · `Main/api/sync_api.py`
- [Analytics API](https://github.com/barryii/fincloud/blob/main/Main/api/dashboard.py): domain services · Dashboard, metrics, resources, budgets, recommendations, anomalies, and export · `Main/api/dashboard.py`
- [Database](https://github.com/barryii/fincloud/blob/main/Main/api/database.py): relational store · Shared persistence for accounts, costs, resources, metrics, budgets, and logs · `Main/api/database.py`
- **Models & schemas**: domain model · Structured entities and API contracts
- [Cloud errors](https://github.com/barryii/fincloud/blob/main/Main/api/aws_error.py): provider handlers · AWS and GCP-specific error handling · `Main/api/aws_error.py`
- [Email service](https://github.com/barryii/fincloud/blob/main/Main/api/email_service.py): notifications · Outbound email delivery for verification and alerts · `Main/api/email_service.py`

### Barry prototype

Earlier multi-cloud prototype with fuller platform stack

- [Barry frontend](https://github.com/barryii/fincloud/tree/main/Barry/frontend): React dashboard · Prototype analytics UI · `Barry/frontend`
- [Barry backend](https://github.com/barryii/fincloud/tree/main/Barry/app): FastAPI app · Prototype API with versioned routes · `Barry/app`
- [K8s stack](https://github.com/barryii/fincloud/tree/main/Barry/k8s): platform · Postgres, Redis, Kong, and Keycloak deployment layer · `Barry/k8s`

### Key experiment

AWS onboarding and cost retrieval experiment

- [Key frontend](https://github.com/barryii/fincloud/tree/main/Key/frontend): Next.js app · AWS account onboarding and cost dashboard UI · `Key/frontend`
- [Key backend](https://github.com/barryii/fincloud/tree/main/Key/backend): FastAPI app · AWS-focused API for cloud accounts and costs · `Key/backend`
- [AWS services](https://github.com/barryii/fincloud/tree/main/Key/backend/app/services/aws): AWS integration · Connection and cost retrieval services · `Key/backend/app/services/aws`
- [CloudFormation](https://github.com/barryii/fincloud/blob/main/Key/cloudformation/finops-iam-role.yaml): infrastructure as code · IAM role setup template for AWS onboarding · `Key/cloudformation/finops-iam-role.yaml`

### External systems

Cloud providers and operational services

- **User browser**: actor · End user interacting with the product
- **AWS APIs**: external cloud · AWS billing, account, and resource data sources
- **GCP APIs**: external cloud · GCP billing and BigQuery-based data sources
- **Email provider**: external service · Outbound mail infrastructure

## Connections

- User browser → Main frontend: uses · Browser interaction with the product
- Main frontend → Shared state: scoped by · UI state is partitioned by account, currency, and date range
- Main frontend → Main backend: HTTP API · Frontend calls backend services through the API client
- Main backend → Auth & setup: auth flows · Login, connection setup, and token handling
- Main backend → Sync pipeline: runs sync · Backend orchestrates provider ingestion
- Main backend → Analytics API: serves features · Domain endpoints power dashboard and analysis views
- Main backend → Database: reads/writes · Persistent domain state and derived analytics
- Main backend → Models & schemas: uses · Shared data structures and schemas
- Main backend → Cloud errors: handles · Provider-specific failure boundaries
- Main backend → Email service: sends · Verification and alert emails
- Auth & setup → AWS APIs: connects · AWS account onboarding and access
- Auth & setup → GCP APIs: connects · GCP setup-token and staged access path
- Sync pipeline → AWS APIs: ingests · AWS cost, asset, and metric sync
- Sync pipeline → GCP APIs: ingests · GCP cost, asset, and metric sync
- Email service → Email provider: delivers via · External email transport
- Barry frontend → Barry backend: HTTP API · Prototype frontend talks to its backend
- Barry backend → K8s stack: deployed with · Explicit infrastructure stack around the app
- Barry backend → Database: persists similar domain · Prototype shares the same product shape of costs, budgets, and resources
- Key frontend → Key backend: HTTP API · AWS onboarding and dashboard UI
- Key backend → AWS services: uses · AWS connection and cost services
- Key frontend → CloudFormation: provisions · IAM role setup for onboarding
- Key backend → CloudFormation: expects · CloudFormation-backed external ID and role flow
