How barryii/fincloud works
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: api Main backend · frontend Main frontend · auth.py Auth & setup · sync_api.py Sync pipeline
Components 21
Main platform
Production FinOps product
- Main frontend · Multi-page dashboard and onboarding UI
Main/frontend - Shared state · Account, currency, and date-range UI scope
Main/frontend/src/context - Main backend · Production API entrypoint and shared wiring
Main/api - Auth & setup · Login, connections, setup tokens, and secrets
Main/api/auth.py - Sync pipeline · AWS/GCP sync orchestration and provider-specific loaders
Main/api/sync_api.py - Analytics API · Dashboard, metrics, resources, budgets, recommendations, anomalies, and export
Main/api/dashboard.py - Database · Shared persistence for accounts, costs, resources, metrics, budgets, and logs
Main/api/database.py - Models & schemas · Structured entities and API contracts
- Cloud errors · AWS and GCP-specific error handling
Main/api/aws_error.py - Email service · Outbound email delivery for verification and alerts
Main/api/email_service.py
Barry prototype
Earlier multi-cloud prototype with fuller platform stack
- Barry frontend · Prototype analytics UI
Barry/frontend - Barry backend · Prototype API with versioned routes
Barry/app - K8s stack · Postgres, Redis, Kong, and Keycloak deployment layer
Barry/k8s
Key experiment
AWS onboarding and cost retrieval experiment
- Key frontend · AWS account onboarding and cost dashboard UI
Key/frontend - Key backend · AWS-focused API for cloud accounts and costs
Key/backend - AWS services · Connection and cost retrieval services
Key/backend/app/services/aws - CloudFormation · IAM role setup template for AWS onboarding
Key/cloudformation/finops-iam-role.yaml
External systems
Cloud providers and operational services
- User browser · End user interacting with the product
- AWS APIs · AWS billing, account, and resource data sources
- GCP APIs · GCP billing and BigQuery-based data sources
- Email provider · Outbound mail infrastructure
Connections 22
- 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