# arvind-narayan/portfolio-returns architecture

> Architecture diagram of the GitHub repository arvind-narayan/portfolio-returns, 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/portfolio-returns
- Repository: https://github.com/arvind-narayan/portfolio-returns

## Overview

##### Main Components Identification
- Entry Point:
- app.py – Acts as the main Streamlit application orchestrator.
- UI/Functional Components (located in the “components” folder):
- portfolio_input.py – Handles the manual and CSV entry of transaction data.
- portfolio_view.py – Responsible for displaying the current portfolio, allocation charts, and transaction history.
- portfolio_analysis.py – Computes and displays performance metrics such as XIRR, Total Return, Annualized Return, etc.
- Utility Modules (from the “utils” folder):
- calculations.py – Performs all necessary financial calculations.
- data_manager.py – Manages data storage and retrieval from Streamlit’s session state.
- stock_api.py – Interacts with the Yahoo Finance API (through yfinance) to fetch current stock prices.
- Supporting Files/Configuration:
- requirements.txt – Lists all project dependencies.
- .devcontainer – Contains development environment configuration (useful for consistent containerized development).
- initial_prompt.txt – Potentially used as a starter text or prompt guide for user input or onboarding.

##### Relationships and Interactions
- User → Streamlit UI (app.py): Interactions (input transactions, view charts, etc.) originate here.
- app.py → Components:
- Calls functions from portfolio_input.py, portfolio_view.py, and portfolio_analysis.py based on the user selection (this could be visualized as different “pages” or “views” within the Streamlit environment).
- Components → Utilities:
- When users input transactions, data_manager.py is called to store session data.
- For calculations such as portfolio performance metrics, components call functions from calculations.py.
- For live stock data, components or utility functions call stock_api.py to fetch information from Yahoo Finance.
- Data Flow:
- Inputs (manual and CSV) pass from the UI components to the backend utility modules.
- Calculated results and fetched data are returned and rendered in the UI.
- External Integration:
- The system interacts with the Yahoo Finance API (internalized in stock_api.py) and uses third-party libraries like Pandas, NumPy, and Plotly for data processing and visualization.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
- The project isolates core functionality into distinct modules (UI rendering, data processing, API integration), simplifying maintenance and promoting modular development.
- Real-time Processing:
- Data stays transient in session state; every user interaction triggers immediate calculations and data fetching.
- Component-Based Design:
- The “components” folder clearly delineates handling of different aspects of portfolio management—input, view, and analysis.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::user

    %% UI / Presentation Layer
    UApp["Streamlit App (app.py)"]:::ui
    PI["Portfolio Input Component"]:::ui
    PV["Portfolio View Component"]:::ui
    PA["Portfolio Analysis Component"]:::ui

    %% Backend / Utility Layer
    Calc["Calculations Module (utils/calculations.py)"]:::backend
    DM["Data Manager (utils/data_manager.py)"]:::backend
    SA["Stock API Integration (utils/stock_api.py)"]:::external
    YF["Yahoo Finance API"]:::external

    %% Supporting Files & Configurations
    subgraph "Supporting Files & Configurations"
        Req["Project Dependencies (requirements.txt)"]:::config
        Dev["Dev Environment (.devcontainer)"]:::config
        IP["Initial Prompt (initial_prompt.txt)"]:::config
    end

    %% Data Flow Connections
    User -->|"interacts"| UApp
    UApp -->|"routes_to"| PI
    UApp -->|"routes_to"| PV
    UApp -->|"routes_to"| PA

    PI -->|"store_transactions"| DM
    PV -->|"retrieve_data"| DM
    PA -->|"calculate_metrics"| Calc
    PA -->|"fetch_stock_data"| SA
    PV -->|"fetch_stock_data"| SA
    SA -->|"calls"| YF

    %% Configurations impact the main app
    Req -.->|"configure"| UApp
    Dev -.->|"configure"| UApp
    IP -.->|"configure"| UApp

    %% Click Events for Components
    click UApp "https://github.com/arvind-narayan/portfolio-returns/blob/main/app.py"
    click PI "https://github.com/arvind-narayan/portfolio-returns/blob/main/components/portfolio_input.py"
    click PV "https://github.com/arvind-narayan/portfolio-returns/blob/main/components/portfolio_view.py"
    click PA "https://github.com/arvind-narayan/portfolio-returns/blob/main/components/portfolio_analysis.py"
    click Calc "https://github.com/arvind-narayan/portfolio-returns/blob/main/utils/calculations.py"
    click DM "https://github.com/arvind-narayan/portfolio-returns/blob/main/utils/data_manager.py"
    click SA "https://github.com/arvind-narayan/portfolio-returns/blob/main/utils/stock_api.py"
    click Req "https://github.com/arvind-narayan/portfolio-returns/blob/main/requirements.txt"
    click Dev "https://github.com/arvind-narayan/portfolio-returns/blob/main/.devcontainer"
    click IP "https://github.com/arvind-narayan/portfolio-returns/blob/main/initial_prompt.txt"

    %% Styles
    classDef user fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef ui fill:#ccf2ff,stroke:#006699,stroke-width:2px;
    classDef backend fill:#ccffcc,stroke:#339933,stroke-width:2px;
    classDef external fill:#fff2cc,stroke:#996600,stroke-width:2px;
    classDef config fill:#e6e6e6,stroke:#666666,stroke-width:2px;
```
