# arvind-narayan/nri-assist architecture

> Architecture diagram of the GitHub repository arvind-narayan/nri-assist, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arvind-narayan/nri-assist
- Repository: https://github.com/arvind-narayan/nri-assist

## Overview

##### Project Identification
- Purpose: NRI-Assist is an AI agent designed to advise NRIs considering a move back to India. The README clearly states that it integrates OpenAI’s Assistants API (using a GPT-4 variant), a Firestore database for backend storage, Google OAuth for user authentication, and Streamlit for the user interface.
- Type: This is a full-stack web application, albeit a relatively lightweight one with a monolithic structure combining the UI and business logic in Python.

##### File Structure
- Main Application Code: The entry point appears to be “NRI-Assist.py.” This file likely initializes the app, sets up routes, and coordinates between components.
- Pages Directory: Contains “About Arvind.py.” In a Streamlit multi-page app, each file within this directory represents a distinct page of the UI, suggesting a modular UI approach.
- Supporting Code: “utils.py” likely contains helper methods and shared logic used across the app. “about_me.txt” and “README.md” support documentation and content.
- Style/Layout: “style.css” is used for custom styling of the Streamlit UI.
- Dev Environment: The “.devcontainer” directory with its configuration indicates that VS Code or similar remote container development is set up, which should be acknowledged as part of the development environment though not directly part of the runtime architecture.
- Dependencies: “requirements.txt” confirms the Python dependencies (which likely include Streamlit, Firestore client library, OAuth libraries, and OpenAI’s API library).

##### Main Components
a. Frontend/UI:
- Streamlit App:
- Main entry: NRI-Assist.py.
- Pages (e.g., About page from pages/About Arvind.py).
- Styling with style.css.
b. Backend/Business Logic:
- AI Integration:
- Integration with OpenAI Assistants API (GPT-4 variant).
- Database Integration:
- Firestore Database acting as the backend data store.
- Authentication:
- Google OAuth handles user authentication.
- Utility Functions:
- utils.py acts as the glue or supporting library for recurring logic.
c. Development & Deployment:
- .devcontainer: Outlines the development environment (container configuration).
- Deployment info (as seen through annotations or logs in the README, e.g., streamlit app URL).

##### Relationships and Interactions
- The UI (front-end) interacts with the backend logic, which in turn:
- Calls the OpenAI API to generate recommendations or responses.
- Reads from and writes to the Firestore database for persistent storage.
- Uses Google OAuth to authenticate and authorize users.
- Data flows from the user (through Streamlit web pages) -> App Logic (in NRI-Assist.py and utils.py) -> External Services (API calls, DB operations).

##### Architectural Patterns and Principles
- Modularization: Separation into different files and directories (e.g., main app file, pages, utilities) supports modular design.
- Service Integration: Demonstrates integration with external APIs (OpenAI, Firestore) and authentication services (Google OAuth).
- Full-Stack (monolithic) Approach: Even though the logic is broken up into multiple scripts, the system design essentially follows a single application concept with externally-provided services.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User
    User["User"]:::user

    %% UI Layer
    subgraph "UI Layer"
        MAIN["NRI-Assist.py (Main App)"]:::frontend
        ABOUT["About Page (pages/About Arvind.py)"]:::frontend
        STYLE["Style Sheet (style.css)"]:::frontend
    end

    %% Backend Business Logic
    subgraph "Backend Business Logic"
        UTILS["utils.py (Utility Functions)"]:::backend
    end

    %% External Services
    subgraph "External Services"
        OPENAI["OpenAI API (GPT-4)"]:::external
        FIRESTORE["Firestore Database"]:::external
        GOOGLE["Google OAuth"]:::external
    end

    %% Development Environment
    subgraph "Development Environment"
        DEV[".devcontainer"]:::dev
    end

    %% Connections
    User -->|"interacts"| MAIN
    User -->|"navigates"| ABOUT
    MAIN -->|"uses"| STYLE
    MAIN -->|"calls"| UTILS
    MAIN -->|"calls"| OPENAI
    MAIN -->|"writes_reads"| FIRESTORE
    MAIN -->|"auth_calls"| GOOGLE

    %% Click Events
    click MAIN "https://github.com/arvind-narayan/nri-assist/blob/main/NRI-Assist.py"
    click ABOUT "https://github.com/arvind-narayan/nri-assist/blob/main/pages/About Arvind.py"
    click STYLE "https://github.com/arvind-narayan/nri-assist/blob/main/style.css"
    click UTILS "https://github.com/arvind-narayan/nri-assist/blob/main/utils.py"
    click DEV "https://github.com/arvind-narayan/nri-assist/blob/main/.devcontainer"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef dev fill:#FFDAB9,stroke:#000,stroke-width:1px;
    classDef user fill:#F5DEB3,stroke:#000,stroke-width:1px;
```
