# chidokato5376/finguard-ai-platform architecture

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

- Interactive diagram: https://gitdiagram.com/chidokato5376/finguard-ai-platform
- Repository: https://github.com/chidokato5376/finguard-ai-platform

## Overview

FinGuard AI is a transaction-risk management platform: prepared transaction data feeds risk scoring, suspicious cases are explained with behavioral and network context, and QAPE prioritizes alerts for human review. Its main project adds DRRE training and quantum-method research; the public demo instead uses heuristic scoring. The dashboard is the user-facing entry point, with story logic coordinating data, scoring and prioritization services. Edges follow sampled code, SOURCE INDEX references or README statements; unsampled page and quantum internals are represented only where documented.

Main entry points: [`Finguard/src/dashboard/story.py`](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/dashboard/story.py) (Story layer), [`Finguard/src/drre/train.py`](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/drre/train.py) (DRRE training), [`Finguard/src/dashboard/app.py`](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/dashboard/app.py) (Dashboard app), [`Finguard/src/dashboard/scoring_service.py`](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/dashboard/scoring_service.py) (Scoring service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_dashboard_app["Dashboard app<br/>[app.py]"]
  node_dashboard_pages["Dashboard pages"]
  node_story["Story layer<br/>[story.py]"]
end

subgraph group_data["Transaction Data"]
  node_data_service["Data service<br/>[data_service.py]"]
  node_loaders["Data loaders<br/>[loaders.py]"]
  node_preprocessing["Preprocessing<br/>[preprocessing.py]"]
  node_schema["Data schema<br/>[schema.py]"]
  node_synthetic_generator["Synthetic data"]
end

subgraph group_risk["Risk Intelligence"]
  node_scoring_service["Scoring service<br/>[scoring_service.py]"]
  node_drre["DRRE model<br/>[model.py]"]
  node_drre_components["DRRE components"]
  node_risk_scoring["Risk scoring engine<br/>[risk_scoring.py]"]
  node_explainability["Explainability<br/>[explain.py]"]
  node_graph_utils["Graph utilities<br/>[graph_utils.py]"]
end

subgraph group_priority["Alert Prioritization"]
  node_qape_service["QAPE service<br/>[qape_service.py]"]
  node_qubo["Alert QUBO<br/>[qubo.py]"]
  node_solvers["QAPE solvers<br/>[solvers.py]"]
  node_quantum{{"Quantum methods"}}
end

subgraph group_research["Model Research"]
  node_training["DRRE training<br/>[train.py]"]
  node_losses["Training losses<br/>[losses.py]"]
  node_metrics["Evaluation metrics<br/>[metrics.py]"]
end

node_analyst(("Bank analyst"))

node_analyst -->|"uses"| node_dashboard_app
node_dashboard_app -->|"lists sources"| node_data_service
node_dashboard_app -->|"loads results"| node_story
node_dashboard_app -->|"routes to"| node_dashboard_pages
node_dashboard_pages -->|"presents"| node_story
node_story -->|"reads data"| node_data_service
node_story -->|"gets scores"| node_scoring_service
node_story -->|"gets priorities"| node_qape_service
node_data_service -.->|"reads processed data"| node_loaders
node_preprocessing -.->|"loads sources"| node_loaders
node_synthetic_generator -->|"uses schema"| node_schema
node_scoring_service -->|"runs model"| node_drre
node_scoring_service -->|"scores embeddings"| node_risk_scoring
node_scoring_service -->|"builds graph"| node_graph_utils
node_drre -->|"uses components"| node_drre_components
node_explainability -.->|"interprets signals"| node_drre
node_qape_service -->|"builds alerts"| node_qubo
node_qape_service -->|"solves batch"| node_solvers
node_solvers -->|"converts problem"| node_qubo
node_solvers -.->|"includes QAOA"| node_quantum
node_training -->|"trains model"| node_drre
node_training -->|"computes losses"| node_losses
node_training -->|"evaluates model"| node_metrics
node_training -->|"uses engine"| node_risk_scoring

click node_dashboard_app "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/dashboard/app.py"
click node_dashboard_pages "https://github.com/chidokato5376/finguard-ai-platform/tree/main/Finguard/src/dashboard/app_pages"
click node_story "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/dashboard/story.py"
click node_data_service "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/dashboard/data_service.py"
click node_loaders "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/data/loaders.py"
click node_preprocessing "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/data/preprocessing.py"
click node_schema "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/data/schema.py"
click node_synthetic_generator "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/data/synthetic_generator.py"
click node_scoring_service "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/dashboard/scoring_service.py"
click node_drre "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/drre/model.py"
click node_drre_components "https://github.com/chidokato5376/finguard-ai-platform/tree/main/Finguard/src/drre"
click node_risk_scoring "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/scoring/risk_scoring.py"
click node_explainability "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/explainability/explain.py"
click node_graph_utils "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/dashboard/graph_utils.py"
click node_qape_service "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/dashboard/qape_service.py"
click node_qubo "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/qape/qubo.py"
click node_solvers "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/qape/solvers.py"
click node_quantum "https://github.com/chidokato5376/finguard-ai-platform/tree/main/Finguard/src/quantum"
click node_training "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/drre/train.py"
click node_losses "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/drre/losses.py"
click node_metrics "https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/evaluation/metrics.py"

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_dashboard_app,node_dashboard_pages,node_story toneBlue
class node_data_service,node_loaders,node_preprocessing,node_schema,node_synthetic_generator toneAmber
class node_scoring_service,node_drre,node_drre_components,node_risk_scoring,node_explainability,node_graph_utils toneMint
class node_qape_service,node_qubo,node_solvers,node_quantum toneRose
class node_training,node_losses,node_metrics,node_analyst toneIndigo
```

## Components

### Dashboard

- [Dashboard app](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/dashboard/app.py): `Finguard/src/dashboard/app.py`
- [Dashboard pages](https://github.com/chidokato5376/finguard-ai-platform/tree/main/Finguard/src/dashboard/app_pages): `Finguard/src/dashboard/app_pages`
- [Story layer](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/dashboard/story.py): `Finguard/src/dashboard/story.py`

### Transaction Data

- [Data service](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/dashboard/data_service.py): `Finguard/src/dashboard/data_service.py`
- [Data loaders](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/data/loaders.py): `Finguard/src/data/loaders.py`
- [Preprocessing](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/data/preprocessing.py): `Finguard/src/data/preprocessing.py`
- [Data schema](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/data/schema.py): `Finguard/src/data/schema.py`
- [Synthetic data](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/data/synthetic_generator.py): `Finguard/src/data/synthetic_generator.py`

### Risk Intelligence

- [Scoring service](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/dashboard/scoring_service.py): `Finguard/src/dashboard/scoring_service.py`
- [DRRE model](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/drre/model.py): `Finguard/src/drre/model.py`
- [DRRE components](https://github.com/chidokato5376/finguard-ai-platform/tree/main/Finguard/src/drre): `Finguard/src/drre`
- [Risk scoring engine](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/scoring/risk_scoring.py): `Finguard/src/scoring/risk_scoring.py`
- [Explainability](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/explainability/explain.py): `Finguard/src/explainability/explain.py`
- [Graph utilities](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/dashboard/graph_utils.py): `Finguard/src/dashboard/graph_utils.py`

### Alert Prioritization

- [QAPE service](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/dashboard/qape_service.py): `Finguard/src/dashboard/qape_service.py`
- [Alert QUBO](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/qape/qubo.py): `Finguard/src/qape/qubo.py`
- [QAPE solvers](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/qape/solvers.py): `Finguard/src/qape/solvers.py`
- [Quantum methods](https://github.com/chidokato5376/finguard-ai-platform/tree/main/Finguard/src/quantum): `Finguard/src/quantum`

### Model Research

- [DRRE training](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/drre/train.py): `Finguard/src/drre/train.py`
- [Training losses](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/drre/losses.py): `Finguard/src/drre/losses.py`
- [Evaluation metrics](https://github.com/chidokato5376/finguard-ai-platform/blob/main/Finguard/src/evaluation/metrics.py): `Finguard/src/evaluation/metrics.py`

### Other components

- **Bank analyst**

## Connections

- Bank analyst → Dashboard app: uses (evidence: `README.md`)
- Dashboard app → Data service: lists sources (evidence: `Finguard/src/dashboard/app.py`)
- Dashboard app → Story layer: loads results (evidence: `Finguard/src/dashboard/app.py`)
- Dashboard app → Dashboard pages: routes to (evidence: `Finguard/src/dashboard/app.py`)
- Dashboard pages → Story layer: presents (evidence: `Finguard/src/dashboard/app_pages/uu_tien.py`)
- Story layer → Data service: reads data (evidence: `Finguard/src/dashboard/story.py`)
- Story layer → Scoring service: gets scores (evidence: `Finguard/src/dashboard/story.py`)
- Story layer → QAPE service: gets priorities (evidence: `Finguard/src/dashboard/story.py`)
- Data service → Data loaders: reads processed data
- Preprocessing → Data loaders: loads sources
- Synthetic data → Data schema: uses schema (evidence: `Finguard/src/data/synthetic_generator.py`)
- Scoring service → DRRE model: runs model (evidence: `Finguard/src/dashboard/scoring_service.py`)
- Scoring service → Risk scoring engine: scores embeddings (evidence: `Finguard/src/dashboard/scoring_service.py`)
- Scoring service → Graph utilities: builds graph (evidence: `Finguard/src/dashboard/scoring_service.py`)
- DRRE model → DRRE components: uses components (evidence: `Finguard/src/drre/model.py`)
- Explainability → DRRE model: interprets signals
- QAPE service → Alert QUBO: builds alerts (evidence: `Finguard/src/dashboard/qape_service.py`)
- QAPE service → QAPE solvers: solves batch (evidence: `Finguard/src/dashboard/qape_service.py`)
- QAPE solvers → Alert QUBO: converts problem (evidence: `Finguard/src/qape/solvers.py`)
- QAPE solvers → Quantum methods: includes QAOA (evidence: `README.md`)
- DRRE training → DRRE model: trains model (evidence: `Finguard/src/drre/train.py`)
- DRRE training → Training losses: computes losses (evidence: `Finguard/src/drre/train.py`)
- DRRE training → Evaluation metrics: evaluates model (evidence: `Finguard/src/drre/train.py`)
- DRRE training → Risk scoring engine: uses engine (evidence: `Finguard/src/drre/train.py`)
