# fumiaki0604/investmentinsight architecture

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

- Interactive diagram: https://gitdiagram.com/fumiaki0604/investmentinsight
- Repository: https://github.com/fumiaki0604/investmentinsight

## Overview

##### Project Type and Purpose
- This is a full-stack analytics application built as a Streamlit front-end (“streamlit_app/”) backed by reusable Python service code (“src/app/”).
- Purpose: fetch mutual fund NAV data from Google Sheets (or local CSV), compute technical indicators and correlations, generate AI-powered analysis via OpenAI, and send notifications to Slack.

##### Top-Level Components
- Presentation Layer (Streamlit UI)
- streamlit_app/app.py – main UI entrypoint with three tabs (detailed analysis, fund list, correlation analysis)
- streamlit_app/utils – helpers for chart drawing, correlation math, Google Sheets I/O, Slack notifications, GPT prompts
- Core Library Layer (src/app)
- config.py – environment and credential management
- data_sources/loader.py – abstracted data ingestion (Google Sheets API or sample CSV)
- indicators/technical.py – computes moving averages, DMI, etc.
- services/analytics_service.py – orchestrates data loading, indicator computation, correlation analysis, AI prompt assembly, Slack trigger logic
- models/responses.py – pydantic models for structured outputs
- main.py – (future) FastAPI skeleton for exposing the same functionality as an API
- External Systems
- Google Sheets – NAV data storage
- OpenAI API – natural-language explanation and report generation
- Slack Webhook – alert notifications
- Local Sample Data
- data/sample_nav.csv – used in dev/test mode

##### Relationships and Interactions
- Streamlit UI calls into streamlit_app/utils to fetch data, compute charts, and display results.
- The Chart/Correlation helpers delegate to src/app/services/analytics_service, which in turn:
a) Reads config (GOOGLE_SPREADSHEET_ID, API keys)
b) Loads raw data via data_sources/loader
c) Feeds data into indicators/technical for metrics and into correlation utils
d) Prepares prompt and calls OpenAI (via gpt_analysis.py)
e) Optionally sends alerts via Slack notifier
- All data flows are unidirectional: Data Source → Analytics Service → UI / AI / Slack.

##### Architectural Patterns and Principles
- Layered Architecture: clear separation between Presentation (Streamlit), Business Logic (analytics_service), Data Access (loader), and External Integrations (OpenAI, Slack).
- Dependency Injection via config.py: environment variables injected at startup.
- Modular Design: utilities and service code are reusable (can be exposed via FastAPI).
- Testable Units: data loader and indicator functions are covered under tests/.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Presentation Layer"
        UI["UI - Streamlit\nstreamlit_app/app.py"]:::ui
        Chart["Chart Helpers\nstreamlit_app/utils/chart_helper.py"]:::ui
        Correlation["Correlation Helpers\nstreamlit_app/utils/correlation_helper.py"]:::ui
        GSheetUI["Google Sheets I/O Helper\nstreamlit_app/utils/gsheet_helper.py"]:::ui
        SlackUI["Slack Notifier\nstreamlit_app/utils/slack_notifier.py"]:::ui
        GPTUI["GPT Prompt & Analysis\nstreamlit_app/utils/gpt_analysis.py"]:::ui
    end

    subgraph "Core Library Layer"
        Config["Configuration Management\nsrc/app/config.py"]:::business
        Loader["Data Loader\nsrc/app/data_sources/loader.py"]:::data
        Indicators["Technical Indicators Computation\nsrc/app/indicators/technical.py"]:::business
        Analytics["Analytics Service & Orchestration\nsrc/app/services/analytics_service.py"]:::business
        Models["Pydantic Response Models\nsrc/app/models/responses.py"]:::business
        Main["FastAPI Skeleton\nsrc/app/main.py"]:::business
    end

    Sheets[(Google Sheets)]:::external
    CSV[(Local Sample NAV CSV\ndata/sample_nav.csv)]:::data
    OpenAI[(OpenAI API)]:::external
    Slack[(Slack Webhook)]:::external
    TestLoader["Data Loader Unit Tests\ntests/test_data_loader.py"]:::external

    UI -->|"uses chart helpers"| Chart
    UI -->|"uses correlation helpers"| Correlation
    UI -->|"uses Google Sheets I/O"| GSheetUI
    UI -->|"uses Slack notifier"| SlackUI
    UI -->|"uses GPT analysis"| GPTUI
    UI -->|"requests analysis"| Analytics

    Chart -->|"delegates to"| Analytics
    Correlation -->|"delegates to"| Analytics
    GSheetUI -->|"delegates to"| Analytics
    SlackUI -->|"delegates to"| Analytics
    GPTUI -->|"delegates to"| Analytics

    Analytics -->|"load configuration"| Config
    Analytics -->|"load data"| Loader
    Loader -->|"fetch from Google Sheets"| Sheets
    Loader -->|"read sample CSV"| CSV
    Analytics -->|"compute technical indicators"| Indicators
    Analytics -->|"call OpenAI API"| OpenAI
    Analytics -->|"send Slack alert"| Slack
    Analytics -->|"return results"| UI

    TestLoader -->|"tests data loader"| Loader

    click UI "https://github.com/fumiaki0604/investmentinsight/blob/master/streamlit_app/app.py"
    click Chart "https://github.com/fumiaki0604/investmentinsight/blob/master/streamlit_app/utils/chart_helper.py"
    click Correlation "https://github.com/fumiaki0604/investmentinsight/blob/master/streamlit_app/utils/correlation_helper.py"
    click GSheetUI "https://github.com/fumiaki0604/investmentinsight/blob/master/streamlit_app/utils/gsheet_helper.py"
    click SlackUI "https://github.com/fumiaki0604/investmentinsight/blob/master/streamlit_app/utils/slack_notifier.py"
    click GPTUI "https://github.com/fumiaki0604/investmentinsight/blob/master/streamlit_app/utils/gpt_analysis.py"
    click Config "https://github.com/fumiaki0604/investmentinsight/blob/master/src/app/config.py"
    click Loader "https://github.com/fumiaki0604/investmentinsight/blob/master/src/app/data_sources/loader.py"
    click Indicators "https://github.com/fumiaki0604/investmentinsight/blob/master/src/app/indicators/technical.py"
    click Analytics "https://github.com/fumiaki0604/investmentinsight/blob/master/src/app/services/analytics_service.py"
    click Models "https://github.com/fumiaki0604/investmentinsight/blob/master/src/app/models/responses.py"
    click Main "https://github.com/fumiaki0604/investmentinsight/blob/master/src/app/main.py"
    click CSV "https://github.com/fumiaki0604/investmentinsight/blob/master/data/sample_nav.csv"
    click TestLoader "https://github.com/fumiaki0604/investmentinsight/blob/master/tests/test_data_loader.py"

    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px,color:#000
    classDef business fill:#90EE90,stroke:#000,stroke-width:1px
    classDef data fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
```
