# dxzielinski/ai-driven-financial-analysis architecture

> Architecture diagram of the GitHub repository dxzielinski/ai-driven-financial-analysis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dxzielinski/ai-driven-financial-analysis
- Repository: https://github.com/dxzielinski/ai-driven-financial-analysis

## Overview

This repo is a **GCP-based, full-stack cloud application** that provides **AI-driven financial tips and saving plans from user transactions**. The file tree strongly suggests three major concerns:
- **`aidfa-frontend/`**: user-facing web UI (likely SPA)
- **`aidfa-backend/`**: API + business logic (transaction processing + AI prompt/orchestration)
- **`aidfa-terraform/`**: infrastructure-as-code provisioning on **Google Cloud Platform**

##### How to mine the repo for the *actual* architecture (avoid guessing)
Because the top-level tree doesn’t expose frameworks/services directly, use the repo itself to drive accuracy:

##### Use Terraform as the source of truth for cloud components
In `aidfa-terraform/`, enumerate:
- Compute: **Cloud Run / GKE / App Engine / Cloud Functions**
- Data: **Firestore / Cloud SQL / BigQuery / Cloud Storage**
- AI: **Vertex AI (Gemini) / custom model endpoints**
- Messaging/Batch: **Pub/Sub / Cloud Tasks / Cloud Scheduler**
- Security: **IAM service accounts, Secret Manager, VPC, Cloud Armor**
- Edge: **Load Balancer, API Gateway, Cloud CDN**
- Observability: **Cloud Logging/Monitoring, Error Reporting, Trace**

##### Inspect backend for runtime and boundaries
In `aidfa-backend/`, identify:
- Entry points (e.g., `main`, `server`, `app`, `index`)
- API style: REST/GraphQL
- Auth middleware (JWT/Firebase/OAuth)
- Modules for:
- transaction ingestion/normalization
- categorization/analytics
- AI prompt building + response parsing
- persistence layer (repositories/DAOs)
- Outbound integrations (bank APIs, LLM APIs, email, etc.)

##### Inspect frontend for hosting and API usage
In `aidfa-frontend/`, identify:
- SPA framework (React/Vue/Angular/Next.js)
- Where it’s hosted (Cloud Storage+CDN vs Cloud Run SSR, etc.)
- How it calls backend (direct HTTPS, via API Gateway)
- Auth flow (Firebase Auth, Google Identity, custom)

These become UI + edge flow elements.

##### What I would expect the final “ma
A single page with:
- Left: User browser
- Middle: Frontend hosting + edge
- Right: Backend API + worker(s)
- Bottom: DB/storage + Vertex AI + async services
- Side: Secrets/IAM/Monitoring attached to backend

## Diagram (Mermaid)

```mermaid
flowchart TD

%% ========= System Context =========
U["End User<br/>(Browser)"]:::actor
D["Admin / Developer"]:::actor

subgraph "AI-Driven Financial Analysis Platform (GCP)"
direction TB

%% ========= Edge / Ingress =========
subgraph "Edge / Ingress"
direction TB
DNS["Cloud DNS<br/>(optional)"]:::gcpOptional
EDGE["HTTPS Load Balancer and/or API Gateway"]:::gcp
CDN["Cloud CDN<br/>(optional)"]:::gcpOptional
end

%% ========= Frontend Hosting =========
subgraph "Frontend"
direction TB
FE["Frontend Web UI (SPA)"]:::app
FEHOSTA["Option A: Static Hosting<br/>(Cloud Storage website)"]:::gcpOptional
FEHOSTB["Option B: Web Hosting<br/>(Cloud Run SSR / same-origin)"]:::gcpOptional
end

%% ========= Backend Runtime =========
subgraph "Backend"
direction TB
API["Backend API Service<br/>(stateless)"]:::app
WORKER["Worker Service<br/>(async processing, optional)"]:::appOptional

subgraph "Backend Components (logical)"
direction TB
ROUTES["API Controllers / Routes"]:::app
AUTH["Auth Middleware<br/>(JWT/Firebase/OAuth)"]:::app
INGEST["Transaction Ingestion Service"]:::app
NORM["Normalization / Categorization"]:::app
ANALYTICS["Financial Analysis Engine<br/>(rules + aggregations)"]:::app
AIORCH["AI Recommendation Orchestrator<br/>(prompts + parsing)"]:::app
REPO["Persistence Layer<br/>(Repositories / DAO)"]:::app
FORMAT["Response Formatter<br/>(tips + saving plan)"]:::app
end
end

%% ========= Data Layer =========
subgraph "Data Layer"
direction TB
DB["Primary Database<br/>(Firestore or Cloud SQL)"]:::db
OBJ["Cloud Storage<br/>(uploads/exports, optional)"]:::storageOptional
BQ["BigQuery<br/>(analytics, optional)"]:::gcpOptional
end

%% ========= AI Layer =========
subgraph "AI Layer"
direction TB
VERTEX["Vertex AI (Gemini) Endpoint"]:::gcp
end

%% ========= Async / Batch (Optional) =========
subgraph "Async / Batch (optional)"
direction TB
PUB["Pub/Sub Topic(s)"]:::gcpOptional
SUB["Pub/Sub Subscription(s)"]:::gcpOptional
TASKS["Cloud Tasks<br/>(optional)"]:::gcpOptional
SCHED["Cloud Scheduler<br/>(optional)"]:::gcpOptional
end

%% ========= Security & Ops =========
subgraph "Security & Operations"
direction TB
SECRETS["Secret Manager<br/>(API keys, config)"]:::sec
IAM["IAM Service Accounts<br/>(least privilege)"]:::sec
OBS["Cloud Logging & Monitoring"]:::ops
end

%% ========= Callouts / Notes =========
NOTES["Notes:<br/>• Separation of concerns: UI vs API vs IaC<br/>• Stateless services; state in DB/Storage<br/>• Config via Secret Manager + env vars<br/>• IaC (Terraform) defines deployed topology"]:::note

end

%% ========= External Systems =========
BANK["External Bank / Transaction Provider<br/>(optional)"]:::external
THIRD["Other Third-Party Providers<br/>(optional)"]:::external

%% ========= Primary Request Flow =========
U -->|"HTTPS GET (HTML/JS)"| EDGE
EDGE -->|"serves SPA assets"| CDN
CDN -->|"static content"| FEHOSTA
EDGE -->|"routes web"| FEHOSTB
FEHOSTA -->|"loads app"| FE
FEHOSTB -->|"loads app"| FE

U -->|"HTTPS JSON + Auth token"| EDGE
EDGE -->|"routes API"| API

%% Backend internal flow
API -->|"handles request"| ROUTES
ROUTES -->|"verifies identity"| AUTH
AUTH -->|"calls"| INGEST
INGEST -->|"normalizes"| NORM
NORM -->|"aggregates"| ANALYTICS
ANALYTICS -->|"builds prompt"| AIORCH
AIORCH -->|"LLM request/response"| VERTEX
AIORCH -->|"persists"| REPO
REPO -->|"read/write"| DB
AIORCH -->|"formats response"| FORMAT
FORMAT -->|"returns tips/plan"| ROUTES
ROUTES -->|"HTTPS response"| API

API -->|"read/write transactions & plans"| DB

%% Optional integrations
INGEST -.->|"fetch transactions (optional)"| BANK
API -.->|"uploads via signed URL (optional)"| OBJ
REPO -.->|"analytics export (optional)"| BQ
API -.->|"3rd-party integration (optional)"| THIRD

%% Optional async processing
API -.->|"publish events (optional)"| PUB
PUB -.->|"fanout"| SUB
SUB -.->|"triggers (optional)"| WORKER
WORKER -.->|"processes"| DB
SCHED -.->|"schedule trigger (optional)"| PUB
TASKS -.->|"deferred jobs (optional)"| WORKER

%% Security & Ops attachments
API -->|"reads secrets"| SECRETS
WORKER -.->|"reads secrets (optional)"| SECRETS
API -->|"runs as"| IAM
WORKER -.->|"runs as (optional)"| IAM
API -->|"logs/metrics/traces"| OBS
WORKER -.->|"logs/metrics (optional)"| OBS

%% ========= Click Events =========
click FE "https://github.com/dxzielinski/ai-driven-financial-analysis/tree/main/aidfa-frontend/"
click API "https://github.com/dxzielinski/ai-driven-financial-analysis/tree/main/aidfa-backend/"
click NOTES "https://github.com/dxzielinski/ai-driven-financial-analysis/blob/main/README.md"
click IAM "https://github.com/dxzielinski/ai-driven-financial-analysis/tree/main/aidfa-terraform/"
click SECRETS "https://github.com/dxzielinski/ai-driven-financial-analysis/tree/main/aidfa-terraform/"
click EDGE "https://github.com/dxzielinski/ai-driven-financial-analysis/tree/main/aidfa-terraform/"
click DB "https://github.com/dxzielinski/ai-driven-financial-analysis/tree/main/aidfa-terraform/"
click PUB "https://github.com/dxzielinski/ai-driven-financial-analysis/tree/main/aidfa-terraform/"
click VERTEX "https://github.com/dxzielinski/ai-driven-financial-analysis/tree/main/aidfa-terraform/"
click OBS "https://github.com/dxzielinski/ai-driven-financial-analysis/tree/main/aidfa-terraform/"
click D "https://github.com/dxzielinski/ai-driven-financial-analysis/blob/main/.gitmodules"

%% ========= Styles =========
classDef actor fill:#ffffff,stroke:#111827,stroke-width:1.5px,color:#111827
classDef app fill:#d1fae5,stroke:#065f46,stroke-width:1.5px,color:#064e3b
classDef appOptional fill:#ecfdf5,stroke:#10b981,stroke-width:1.5px,color:#065f46,stroke-dasharray: 5 4
classDef gcp fill:#dbeafe,stroke:#1d4ed8,stroke-width:1.5px,color:#1e3a8a
classDef gcpOptional fill:#eff6ff,stroke:#3b82f6,stroke-width:1.5px,color:#1d4ed8,stroke-dasharray: 5 4
classDef db fill:#e0e7ff,stroke:#3730a3,stroke-width:1.5px,color:#312e81
classDef storageOptional fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#075985,stroke-dasharray: 5 4
classDef sec fill:#fef9c3,stroke:#a16207,stroke-width:1.5px,color:#854d0e
classDef ops fill:#fde68a,stroke:#b45309,stroke-width:1.5px,color:#92400e
classDef external fill:#f3f4f6,stroke:#4b5563,stroke-width:1.5px,color:#111827,stroke-dasharray: 4 4
classDef note fill:#fff7ed,stroke:#c2410c,stroke-width:1.5px,color:#7c2d12
```
