# minhe51805/hdbank_team architecture

> Architecture diagram of the GitHub repository minhe51805/hdbank_team, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/minhe51805/hdbank_team
- Repository: https://github.com/minhe51805/hdbank_team

## Overview

##### Project Type and Purpose
- Type: Full-stack, end-to-end financial assistant combining Web UI (React), Backend API (Node.js/Express), AI/ML + LLM (Python), Blockchain logging (Solidity/Hardhat), and Zalo Bot integration (FastAPI).
- Purpose: Provide personalized financial recommendations, record advice immutably on-chain, and offer multi-channel access (Web + Zalo).

##### File Structure
a. Top-level directories:
– blockchain/ (Solidity contracts, Hardhat config, deploy scripts)
– server/ (Express REST API, on-chain hooks, explorer endpoints)
– hdbank-react/ (React + TypeScript frontend)
– notebooks & models (Python Jupyter notebooks for training & LLM chat)
– zalo_bot_integration.py & related scripts (FastAPI webhook for Zalo Bot)
– docker-compose.yml (Postgres setup)
b. Patterns:
– Layered separation (Frontend ↔ API ↔ ML ↔ Blockchain ↔ Messaging)
– Event hooks for on-chain logging
– Use of Docker/Hardhat for local dev environments

##### README Insights
- 4 main layers:
1) Frontend (React/TS)
2) Backend API (Node/Express + ethers.js + Postgres)
3) AI/ML & LLM (Python, scikit-learn, joblib, Jupyter, Gemini LLM)
4) Blockchain (Solidity, Hardhat)
5) Zalo Bot (Python FastAPI)
- Data flow: Notebook → PostgreSQL → Backend /signals/offer → Frontend UI → Hooks → AdviceLog on-chain
- Additional: explorer endpoints, Docker-compose for Postgres, Tailscale funnel for webhook exposure

##### Relationships & Data Flows
- Web UI → HTTP JSON → Backend /signals/offer → Postgres
- Backend on user action → ethers.js → Hardhat node → AdviceLog event
- Notebook training → writes predictions to Postgres
- Frontend polls /signals/offer & /advice/logs for Explorer
- Zalo Bot message → FastAPI webhook → CashyBear chat LLM → Backend log hook → Blockchain
- Backend explorer APIs read on-chain events → Frontend Explorer page

##### Architectural Patterns & Principles
– Separation of concerns: UI, API, ML, Blockchain, Messaging
– Event-driven extension: hooks to capture user actions
– Microservice‐style boundaries: each layer can be containerized
– Immutable logging: write-only blockchain contract events
– Data caching & model artifacts managed separately

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Users & Clients
    WebBrowser(("Web Browser")):::external
    ZaloApp(("Zalo App")):::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Frontend["hdbank-react (React/TS)"]:::frontend
    end

    %% Backend API Layer
    subgraph "Backend API Layer"
        direction TB
        API["server/index.js (Node.js/Express)"]:::api
        PgClient["pg (Postgres client)"]:::api
        Ethers["ethers.js (Blockchain RPC)"]:::api
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Postgres[(PostgreSQL)]:::db
    end

    %% AI/ML & LLM Services
    subgraph "AI/ML & LLM Services"
        direction TB
        NotebookTrain["CustomerPotentialModel.ipynb"]:::ml
        ModelArtifact["customer_propensity_model.joblib"]:::ml
        NotebookChat["CashyBear_Persona_Chatbot.ipynb"]:::ml
        NotebookLLM["persona_based_conversational_LLM.ipynb"]:::ml
        LLMService["Gemini LLM API"]:::external
    end

    %% Blockchain Layer
    subgraph "Blockchain Layer"
        direction TB
        HardhatNode[(Hardhat Local Network)]:::blockchain
        AdviceContract["AdviceLog.sol"]:::blockchain
        DeployScript["deploy.js"]:::blockchain
        Artifacts[(artifacts & artifacts-exports)]:::blockchain
    end

    %% Zalo Bot Integration
    subgraph "Zalo Bot Integration"
        direction TB
        BotWebhook["zalo_bot_integration.py (FastAPI)"]:::bot
        SetupWebhook["setup_zalo_webhook.py"]:::bot
        StartIntegration["start_zalo_integration.py"]:::bot
        Tailscale["Tailscale Funnel"]:::external
    end

    %% n8n Workflow
    n8nWorkflow["workflow_chat_zalobot.json"]:::bot

    %% Hooks & Supporting Scripts
    subgraph "On-chain Hooks & Scripts"
        direction TB
        HookChat["hook_chat_reply.js"]:::script
        HookPlanAccept["hook_plan_accept.js"]:::script
        HookPlanProp["hook_plan_propose.js"]:::script
        PostLog1["post_advice_log.js"]:::script
        PostLog2["post_advice_log2.js"]:::script
        SeedAccounts["seed_accounts.py"]:::script
    end

    %% Data Flows
    WebBrowser -->|HTTP JSON| Frontend
    Frontend -->|GET /signals/offer| API
    API -->|SQL queries| Postgres
    NotebookTrain -->|writes predictions| Postgres
    Frontend -->|GET /advice/logs| API
    API -->|ethers.js calls| HardhatNode
    HardhatNode --> AdviceContract
    AdviceContract -->|events| API
    API -->|reads events| Artifacts
    ZaloApp -->|message| BotWebhook
    BotWebhook -->|LLM chat| NotebookChat
    NotebookChat -->|reply via API| API
    BotWebhook -->|Webhook POST| API
    API -->|hook chat reply| HookChat
    API -->|hook plan propose| HookPlanProp
    API -->|hook plan accept| HookPlanAccept
    HookChat -->|post on-chain| PostLog1
    HookPlanProp -->|post on-chain| PostLog2
    HookPlanAccept -->|post on-chain| PostLog1
    SeedAccounts --> Postgres
    n8nWorkflow -->|triggers BotWebhook| BotWebhook
    BotWebhook -->|dev HTTPS| Tailscale

    %% Click Events
    click Frontend "https://github.com/minhe51805/hdbank_team/tree/main/hdbank-react/"
    click API "https://github.com/minhe51805/hdbank_team/blob/main/server/index.js"
    click PgClient "https://github.com/minhe51805/hdbank_team/blob/main/server/package.json"
    click Postgres "https://github.com/minhe51805/hdbank_team/blob/main/docker-compose.yml"
    click NotebookTrain "https://github.com/minhe51805/hdbank_team/blob/main/CustomerPotentialModel.ipynb"
    click ModelArtifact "https://github.com/minhe51805/hdbank_team/blob/main/customer_propensity_model.joblib"
    click NotebookChat "https://github.com/minhe51805/hdbank_team/blob/main/CashyBear_Persona_Chatbot.ipynb"
    click NotebookLLM "https://github.com/minhe51805/hdbank_team/blob/main/persona_based_conversational_LLM.ipynb"
    click AdviceContract "https://github.com/minhe51805/hdbank_team/blob/main/blockchain/contracts/AdviceLog.sol"
    click DeployScript "https://github.com/minhe51805/hdbank_team/blob/main/blockchain/scripts/deploy.js"
    click Artifacts "https://github.com/minhe51805/hdbank_team/tree/main/blockchain/artifacts/"
    click BotWebhook "https://github.com/minhe51805/hdbank_team/blob/main/zalo_bot_integration.py"
    click SetupWebhook "https://github.com/minhe51805/hdbank_team/blob/main/setup_zalo_webhook.py"
    click StartIntegration "https://github.com/minhe51805/hdbank_team/blob/main/start_zalo_integration.py"
    click n8nWorkflow "https://github.com/minhe51805/hdbank_team/blob/main/n8n/workflow_chat_zalobot.json"
    click HookChat "https://github.com/minhe51805/hdbank_team/blob/main/scripts/hook_chat_reply.js"
    click HookPlanProp "https://github.com/minhe51805/hdbank_team/blob/main/scripts/hook_plan_propose.js"
    click HookPlanAccept "https://github.com/minhe51805/hdbank_team/blob/main/scripts/hook_plan_accept.js"
    click PostLog1 "https://github.com/minhe51805/hdbank_team/blob/main/scripts/post_advice_log.js"
    click PostLog2 "https://github.com/minhe51805/hdbank_team/blob/main/scripts/post_advice_log2.js"
    click SeedAccounts "https://github.com/minhe51805/hdbank_team/blob/main/scripts/seed_accounts.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#1E70BF,color:#000
    classDef api fill:#C8F7C5,stroke:#2E8B57,color:#000
    classDef db fill:#E2F0CB,stroke:#6B8E23,color:#000
    classDef ml fill:#FFE4B5,stroke:#FF8C00,color:#000
    classDef blockchain fill:#F5C6EC,stroke:#C71585,color:#000
    classDef bot fill:#FFD1DC,stroke:#FF69B4,color:#000
    classDef external fill:#E8E8E8,stroke:#A9A9A9,color:#000
    classDef script fill:#FFE4E1,stroke:#CD5C5C,color:#000
```
