# pallavi-sinha-12/expense-tracker-chatbot architecture

> Architecture diagram of the GitHub repository pallavi-sinha-12/expense-tracker-chatbot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pallavi-sinha-12/expense-tracker-chatbot
- Repository: https://github.com/pallavi-sinha-12/expense-tracker-chatbot

## Overview

##### Project Type and Purpose
- This is a full-stack conversational AI expense-tracker.
- It uses Rasa (NLU + dialogue management), custom Python actions for DB I/O, a Streamlit front-end chat interface, and an optional static website that embeds the chatbot via an iframe.
- It supports two database backends (PostgreSQL or Azure SQL) and can produce both on-screen visualizations and downloadable CSVs.

##### Main Components
a. Presentation Layer
- Streamlit App (Expense-Tracker-Chatbot.py, runs on port 8501) – the primary chat UI.
b. Conversational Engine
- Rasa Core & NLU Server (rasa run --enable-api → port 5005)
– config.yml (pipeline & policy definitions)
– data/nlu.yml, data/rules.yml, data/stories.yml (training data)
– domain.yml (intents, entities, actions, responses)
– endpoints.yml (action endpoint configuration)
- Rasa Actions Server (rasa run actions → port 5055 by default) – hosts actions/actions.py
c. Application/Service Layer
- Custom Actions (actions/actions.py) – handles expense-entry workflows, chart requests, date parsing, confirmation dialogs.
- Data Exporter (data_exporter/CSVFile.py) – exports chart data to CSV when requested.
d. Data Access Layer
- DatabaseFactory (database/DatabaseFactory.py) – Factory pattern to instantiate connector + query objects based on the chosen DB type.
- Abstract Base Classes
– DatabaseConnector (database/DatabaseConnector.py)
– VisualisationQuery (database/VisualisationQuery.py)
- Concrete Implementations
– PostgreSQL
· PostgresSQLDatabaseConfig.py (connection params)
· PostgresSQLDatabaseConnector.py (psycopg2‐based CRUD)
· PostgresVisualisationQuery.py (SQL for charts)
· setup_script.sql (schema creation)
– Azure SQL
· AzureKeyVault.py (fetches secret via Azure SDK)
· AzureSQLDatabaseConfig.py
· AzureSQLDatabaseConnector.py (pyodbc‐based CRUD)
· AzureSQLVisualisationQuery.py
- Configuration File (database/database_config.yaml) – generated by create_database_config.py
e. Data Storage & External Services
- Azure SQL Database (+ Azure Key Vault for secrets)
- PostgreSQL (optional)
- ODBC driver or psycopg2 driver

##### Relationships & Interactions
- The **user** (browser) → interacts with **Streamlit App** (or via static website iframe).
- Streamlit forwards user messages via HTTP to the **Rasa Core Server** (5005).
- Rasa Core processes intent/entity → if a custom action is needed, it calls the **Rasa Actions Server**.
- The action code uses **DatabaseFactory** → instantiates a connector & query object → performs CRUD or fetches visualization data from the chosen **Database**.
- Visualization data returns to Streamlit, which renders an interactive bar chart or triggers CSV export via **data_exporter**.

##### Architectural Patterns & Design Principles
- Layered Architecture (Presentation → Application → Data Access → Persistence)
- Factory Pattern (DatabaseFactory) for pluggable DB providers
- Dependency Inversion: actions depend on abstract connectors & queries
- Process Separation:
- Streamlit App (UI)
- Rasa Core + NLU
- Rasa Actions
- Static Web Server
- Extensibility Points: add new DB by subclassing DatabaseConnector + VisualisationQuery

##### Essential Elements
- Ports & protocols on connectors (e.g., HTTP 5005, psycopg2)
- Factory Pattern call from Actions to DatabaseFactory → Connector + Query

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser["User Browser"]:::external
        StreamlitApp["Streamlit App\n(Expense-Tracker-Chatbot.py)"]:::ui
        subgraph "Static Website"
            direction TB
            HTML["index.html"]:::ui
            CSS["styles.css"]:::ui
            JS["script.js"]:::ui
        end
    end

    %% Conversational Engine
    subgraph "Conversational Engine"
        direction TB
        RasaCore["Rasa NLU + Core\nHTTP 5005"]:::engine
        Endpoints["endpoints.yml"]:::engine
        Config["config.yml"]:::engine
        NLUData["data/nlu.yml"]:::engine
        Rules["data/rules.yml"]:::engine
        Stories["data/stories.yml"]:::engine
        Domain["domain.yml"]:::engine
        ActionsServer["Rasa Actions Server\nHTTP 5055"]:::engine
    end

    %% Application/Service Layer
    subgraph "Application / Service Layer"
        direction TB
        CustomActions["Custom Actions\nactions/actions.py"]:::service
        DataExporter["Data Exporter\nCSVFile.py"]:::service
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        direction TB
        Factory["DatabaseFactory\nDatabaseFactory.py"]:::dataaccess
        AbstractConnector["DatabaseConnector\nDatabaseConnector.py"]:::dataaccess
        AbstractQuery["VisualisationQuery\nVisualisationQuery.py"]:::dataaccess

        subgraph "PostgreSQL Implementation"
            direction TB
            PGConfig["PostgresSQLDatabaseConfig.py"]:::dataaccess
            PGConnector["PostgresSQLDatabaseConnector.py"]:::dataaccess
            PGQuery["PostgresVisualisationQuery.py"]:::dataaccess
            PGSetup["setup_script.sql"]:::dataaccess
        end

        subgraph "Azure SQL Implementation"
            direction TB
            Vault["AzureKeyVault.py"]:::dataaccess
            AzureConfig["AzureSQLDatabaseConfig.py"]:::dataaccess
            AzureConnector["AzureSQLDatabaseConnector.py"]:::dataaccess
            AzureQuery["AzureSQLVisualisationQuery.py"]:::dataaccess
        end

        ConfigGen["create_database_config.py"]:::dataaccess
    end

    %% Data Storage & External Services
    subgraph "Data Storage & External"
        direction TB
        PostgreSQLDB["PostgreSQL DB"]:::external
        AzureSQLDB["Azure SQL DB"]:::external
        KeyVault["Azure Key Vault"]:::external
    end

    %% Flows
    Browser -->|"HTTP 8501"| StreamlitApp
    Browser -->|"embeds iframe"| HTML
    HTML -->|"loads CSS/JS"| CSS
    HTML -->|"loads JS"| JS
    StreamlitApp -->|"HTTP 5005"| RasaCore
    RasaCore -->|"calls actions\nHTTP 5055"| ActionsServer
    ActionsServer -->|"invoke"| CustomActions
    CustomActions -->|"uses"| Factory
    Factory --> AbstractConnector
    Factory --> AbstractQuery
    AbstractConnector -->|"psycopg2 / pyodbc"| PGConnector
    AbstractConnector -->|"psycopg2 / pyodbc"| AzureConnector
    AbstractQuery --> PGQuery
    AbstractQuery --> AzureQuery
    PGConnector --> PGConfig
    AzureConnector --> AzureConfig
    AzureConnector --> Vault
    PGConnector --> PostgreSQLDB
    AzureConnector --> AzureSQLDB
    CustomActions -->|"export CSV"| DataExporter
    DataExporter -->|"writes file"| StreamlitApp

    %% Optional dashed for Postgres/Azure choice
    Factory -.-> PGConnector
    Factory -.-> AzureConnector

    %% Click Events
    click StreamlitApp "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/Expense-Tracker-Chatbot.py"
    click HTML "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/website/index.html"
    click CSS "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/website/styles.css"
    click JS "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/website/script.js"
    click Config "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/config.yml"
    click NLUData "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/data/nlu.yml"
    click Rules "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/data/rules.yml"
    click Stories "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/data/stories.yml"
    click Domain "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/domain.yml"
    click Endpoints "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/endpoints.yml"
    click ActionsServer "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/actions/actions.py"
    click DataExporter "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/data_exporter/CSVFile.py"
    click Factory "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/database/DatabaseFactory.py"
    click AbstractConnector "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/database/DatabaseConnector.py"
    click AbstractQuery "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/database/VisualisationQuery.py"
    click PGConfig "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/database/postgres_sql_database/PostgresSQLDatabaseConfig.py"
    click PGConnector "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/database/postgres_sql_database/PostgresSQLDatabaseConnector.py"
    click PGQuery "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/database/postgres_sql_database/PostgresVisualisationQuery.py"
    click PGSetup "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/database/postgres_sql_database/setup_script.sql"
    click Vault "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/database/azure_sql_database/AzureKeyVault.py"
    click AzureConfig "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/database/azure_sql_database/AzureSQLDatabaseConfig.py"
    click AzureConnector "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/database/azure_sql_database/AzureSQLDatabaseConnector.py"
    click AzureQuery "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/database/azure_sql_database/AzureSQLVisualisationQuery.py"
    click ConfigGen "https://github.com/pallavi-sinha-12/expense-tracker-chatbot/blob/main/database/create_database_config.py"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#005B96,color:#000
    classDef engine fill:#DFF2BF,stroke:#4F8A10,color:#000
    classDef service fill:#FFE4B5,stroke:#CC5500,color:#000
    classDef dataaccess fill:#FFF2CC,stroke:#997300,color:#000
    classDef external fill:#E0E0E0,stroke:#666,color:#000
```
