# george-dominic/portfolio-performance architecture

> Architecture diagram of the GitHub repository george-dominic/portfolio-performance, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/george-dominic/portfolio-performance
- Repository: https://github.com/george-dominic/portfolio-performance

## Overview

##### Project type and purpose
- This is a lightweight Python‐based automated analytics pipeline. It fetches portfolio holdings and price/sector data, computes performance metrics, generates an LLM‐driven summary, and emails a daily report.
- Not a web front‑end or microservice suite, but a single orchestration script with clearly separated functional modules and external API integrations.

##### File structure
- Top‑level scripts & modules:
- prep_email.py (primary entry point for generating and sending the email)
- main.py (alternative CLI entry)
- auth_handler.py & token_manager.py (authenticate & manage tokens for Zerodha KiteConnect)
- news.py (fetch MarketAux news)
- ai_summary.py (invoke Ollama LLaMA 3.2 for text summarization)
- config.py (load environment variables and API keys)
- requirements.txt (.pip dependencies)
- No database or persistent storage; all data flows at runtime.
- External dependencies indicated by imports and README (Zerodha KiteConnect API, yFinance, MarketAux, Ollama, Resend).

##### README for additional insights
- Pipeline stages: holdings fetch → price/sector data → metrics computation (1-day, MTD, top movers, sector returns, benchmark) → LLM summarization → email digest.
- Key external services: KiteConnect, yFinance, MarketAux, Ollama (LLaMA 3.2 via ollama), Resend (email delivery).
- Configuration via .env (API keys, emails).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points and Configuration
    Config["config.py"]:::config
    Orchestrator["prep_email.py"]:::orchestrator
    CLI["main.py"]:::orchestrator

    Config -->|"loads env vars"| Orchestrator
    Config -->|"loads env vars"| CLI
    CLI -->|"invokes"| Orchestrator

    %% Ingestion Layer
    subgraph "Ingestion" 
        direction TB
        AuthHandler["auth_handler.py"]:::ingestion
        TokenManager["token_manager.py"]:::ingestion
        NewsFetcher["news.py"]:::ingestion
    end

    Orchestrator -->|"Python SDK call & OAuth"| AuthHandler
    AuthHandler -->|"manage tokens"| TokenManager
    AuthHandler -->|"REST JSON"| KiteConnect
    Orchestrator -->|"Python SDK call"| yFinance
    Orchestrator -->|"invoke"| NewsFetcher
    NewsFetcher -->|"REST JSON"| MarketAux

    %% Processing Layer
    subgraph "Processing" 
        direction TB
        Metrics["Metrics Processor"]:::processing
        Summarizer["ai_summary.py"]:::processing
    end

    Orchestrator -->|"data inputs"| Metrics
    Metrics -->|"raw metrics & news"| Summarizer
    Summarizer -->|"gRPC"| Ollama

    %% Delivery Layer
    subgraph "Delivery" 
        direction TB
        EmailBuilder["Email Builder & Sender"]:::delivery
    end

    Orchestrator -->|"build template"| EmailBuilder
    EmailBuilder -->|"REST JSON"| Resend

    %% External Services
    subgraph "External Services"
        direction TB
        KiteConnect["Zerodha KiteConnect API"]:::external
        yFinance["yFinance SDK"]:::external
        MarketAux["MarketAux API"]:::external
        Ollama["Ollama LLaMA 3.2"]:::external
        Resend["Resend API"]:::external
    end

    %% Click Events
    click Orchestrator "https://github.com/george-dominic/portfolio-performance/blob/main/prep_email.py"
    click CLI "https://github.com/george-dominic/portfolio-performance/blob/main/main.py"
    click Config "https://github.com/george-dominic/portfolio-performance/blob/main/config.py"
    click AuthHandler "https://github.com/george-dominic/portfolio-performance/blob/main/auth_handler.py"
    click TokenManager "https://github.com/george-dominic/portfolio-performance/blob/main/token_manager.py"
    click NewsFetcher "https://github.com/george-dominic/portfolio-performance/blob/main/news.py"
    click Summarizer "https://github.com/george-dominic/portfolio-performance/blob/main/ai_summary.py"
    click requirements "https://github.com/george-dominic/portfolio-performance/blob/main/requirements.txt"

    %% Styles
    classDef config fill:#cccccc,stroke:#666666,color:#000000
    classDef orchestrator fill:#c199ff,stroke:#7f00ff,color:#000000
    classDef ingestion fill:#add8e6,stroke:#0000ff,color:#000000
    classDef processing fill:#90ee90,stroke:#008000,color:#000000
    classDef delivery fill:#ffcc99,stroke:#ff9900,color:#000000
    classDef external fill:#f0f0f0,stroke:#999999,color:#000000
```
