# vidyutchakrabarti/rail-madad architecture

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

- Interactive diagram: https://gitdiagram.com/vidyutchakrabarti/rail-madad
- Repository: https://github.com/vidyutchakrabarti/rail-madad

## Overview

##### Project type and purpose
- This is a full-stack, role-based complaint management web app built with Streamlit.
- It provides separate dashboards for passengers, staff, supervisors, analysts, and admins; integrates AI agents for complaint routing/analysis; and uses external APIs (Google Gemini, Indian Railway API, Google Search).

##### File structure
- Top-level UI entrypoints:
- main_app.py – the full RBAC app
- app.py – a minimal demo version
- app_pages/ – per-role page modules (admin_dashboard.py, passenger_dashboard.py, etc.)
- auth/ – RBAC helpers and credentials files (credentials_example.yaml, rbac_utils.py)
- agents.py, tasks.py, main.py – orchestration of AI agents (complaint analysis, routing)
- helperfunctions.py – complaint storage (log_file.json), analytics helper functions
- tools.py – wrappers for external services (train status, web search, wiki)
- vars.py – configuration mappings (departments, routing hints)
- Configuration: .streamlit/config.toml, secrets_template.toml, environment variables

##### README for additional insights
- Confirms AI complaint analysis/workflow, multi-department routing, dashboards, and live chat assistant
- Details required API keys (Gemini, RapidAPI, Serper) and secrets management
- Mentions JSON log_file.json as primary data store

a. Main components:
- Presentation Layer (Streamlit UI)
- Business Logic Layer (RBAC auth module, page controllers, AI agents orchestrator)
- Data Layer (log_file.json, credentials.yaml, local config)
- External Services (Google Gemini, RapidAPI IRCTC, Serper Search)
b. Relationships/Interactions:
- UI pages call backend controllers in app_pages → invoke helperfunctions or AI agents
- RBAC auth module mediates access to each page
- Agents orchestrate complaint analysis and routing via tools.py (calls external APIs)
- helperfunctions persist complaints to log_file.json and aggregate analytics
c. Architectural patterns/design principles:
- Layered architecture (UI → controllers → services → data store)
- Modular page-per-role for separation of concerns
- Dependency injection of credentials via environment or Streamlit secrets
- External API adapter pattern in tools.py
d. Relevant technologies:
- Python 3, Streamlit framework for UI
- JSON file as lightweight datastore
- YAML for credentials
- Google Generative AI (Gemini), RapidAPI IRCTC, Serper search

- UI → Auth Module (login flow)
- UI → Controllers → AI Agents → External APIs → Agents → helperfunctions → Data Store
- UI ← helperfunctions (for dashboard analytics)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        UI1["Streamlit UI Entrypoint: main_app.py"]:::ui
        UI2["Streamlit UI Entrypoint: app.py"]:::ui
        UI3["Streamlit UI Entrypoint: app_simplified.py"]:::ui
        subgraph "Per-Role & Shared Pages"
            direction TB
            P1["Passenger Dashboard"]:::ui
            P2["Staff Dashboard"]:::ui
            P3["Supervisor Analytics"]:::ui
            P4["Admin Dashboard"]:::ui
            P5["Analyst/Analytics Dashboard"]:::ui
            P6["Complaint Lodging Page"]:::ui
            P7["My Complaints Page"]:::ui
            P8["Complaints Directory"]:::ui
            P9["Live Chat Assistant"]:::ui
        end
    end

    %% Authentication Layer
    subgraph "RBAC Auth Module" 
        direction TB
        A1["rbac_utils.py"]:::service
        A2["credentials_example.yaml"]:::service
        A3["__init__.py"]:::service
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        subgraph "Controllers & Helpers"
            direction TB
            C1["app_pages Controllers"]:::service
            H1["helperfunctions.py"]:::service
        end
        subgraph "AI Agents Orchestrator"
            direction TB
            AG1["agents.py"]:::service
            AG2["tasks.py"]:::service
            AG3["main.py"]:::service
        end
        E1["tools.py (External API Adapters)"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        D1["log_file.json"]:::data
    end

    %% Configuration & Environment
    subgraph "Configuration & Environment"
        direction TB
        CFG1["vars.py"]:::config
        CFG2[".streamlit/config.toml"]:::config
        CFG3["secrets_template.toml"]:::config
    end

    %% External Services
    subgraph "External Services"
        direction TB
        EX1["Google Gemini"]:::external
        EX2["RapidAPI IRCTC"]:::external
        EX3["Serper Search"]:::external
    end

    %% Connections
    UI1 -->|uses| P1
    UI1 -->|uses| P2
    UI1 -->|uses| P3
    UI1 -->|uses| P4
    UI1 -->|uses| P5
    UI1 -->|uses| P6
    UI1 -->|uses| P7
    UI1 -->|uses| P8
    UI1 -->|uses| P9
    UI2 -->|uses| P6
    UI3 -->|uses| P6

    P1 -->|auth| A1
    P2 -->|auth| A1
    P3 -->|auth| A1
    P4 -->|auth| A1
    P5 -->|auth| A1
    P6 -->|auth| A1
    P7 -->|auth| A1
    P8 -->|auth| A1
    P9 -->|auth| A1

    P1 -->|invoke| C1
    P2 -->|invoke| C1
    P3 -->|invoke| C1
    P4 -->|invoke| C1
    P5 -->|invoke| C1
    P6 -->|invoke| C1
    P7 -->|invoke| C1
    P8 -->|invoke| C1
    P9 -->|invoke| C1

    C1 -->|call analysis| AG1
    AG1 -->|delegate tasks| AG2
    AG2 -->|run workflow| AG3
    AG3 -->|use adapters| E1
    E1 -->|calls| EX1
    E1 -->|calls| EX2
    E1 -->|calls| EX3

    AG3 -->|store results| H1
    H1 -->|persist| D1
    H1 -->|aggregate| C1

    CFG1 -->|configs| AG3
    CFG1 -->|mappings| C1
    CFG2 -->|secrets| A1
    CFG3 -->|secrets| A1

    %% Click Events
    click UI1 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/main_app.py"
    click UI2 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/app.py"
    click UI3 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/app_simplified.py"
    click P1 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/app_pages/passenger_dashboard.py"
    click P2 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/app_pages/staff_dashboard.py"
    click P3 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/app_pages/supervisor_analytics.py"
    click P4 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/app_pages/admin_dashboard.py"
    click P5 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/app_pages/analytics_dashboard.py"
    click P6 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/app_pages/complaint_lodger.py"
    click P7 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/app_pages/my_complaints.py"
    click P8 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/app_pages/complaints_directory.py"
    click P9 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/app_pages/livechat.py"
    click A1 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/auth/rbac_utils.py"
    click A2 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/auth/credentials_example.yaml"
    click A3 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/auth/__init__.py"
    click AG1 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/agents.py"
    click AG2 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/tasks.py"
    click AG3 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/main.py"
    click E1 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/tools.py"
    click H1 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/helperfunctions.py"
    click D1 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/log_file.json"
    click CFG1 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/vars.py"
    click CFG2 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/.streamlit/config.toml"
    click CFG3 "https://github.com/vidyutchakrabarti/rail-madad/blob/main/secrets_template.toml"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef service fill:#E6F7E6,stroke:#2E8B57,stroke-width:1px
    classDef data fill:#FFF4CC,stroke:#DAA520,stroke-width:1px
    classDef external fill:#FFE6E6,stroke:#DC143C,stroke-width:1px
    classDef config fill:#F0F0F0,stroke:#808080,stroke-width:1px
```
