# austin-starks/finangpt architecture

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

- Interactive diagram: https://gitdiagram.com/austin-starks/finangpt
- Repository: https://github.com/austin-starks/finangpt

## Overview

##### Main Components
- Command Line / Entry Point: The process is started with either chat.py (which accepts a --use-ollama flag) or main.py. This is the application’s entry point that parses input and triggers further execution.
- API Communication Modules:
- simfin.py: Handles interactions with the SimFin API to retrieve financial data.
- openai.py: Contains the logic to call the OpenAI API to generate text analysis.
- ollama.py: Provides the functionality to call the Ollama open-source model as an alternative to OpenAI.
- Configuration & Environment Handling: The application relies on environment variables (loaded from a .env file) for keys and settings. Although not explicitly a “module,” this is a key cross-cutting concern.
- Business Logic: The main script (likely chat.py or main.py) ties together the flow: it retrieves data, chooses the analysis service based on provided flags, and produces formatted financial insights.

##### Relationships and Interactions
- The entry point (chat.py/main.py) starts the process and loads configuration.
- Simultaneously, simfin.py is used to query and pull the financial information for the targeted company.
- Once the data is retrieved, it is passed along to the analysis module, which then formats and returns the analysis (summary, recommendations, etc.). The output is then presented to the user (console output).

##### Architectural Patterns and Design Principles
- Modularity: Despite the relatively flat structure, the system is organized into separate files handling different responsibilities (data retrieval vs. analysis generation).
- Clear Separation of Concerns: Each module is focused on a single external service, which makes the selection between OpenAI and Ollama straightforward.
- External Integration: The design shows integration with external APIs (SimFin, OpenAI, and optionally Ollama) and illustrates how environmental configuration drives the integration process.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Application Layer
    subgraph "Application Layer"
        CLI["Entry Point / CLI Interface (chat.py & main.py)"]:::cli
        Config["Configuration Manager (.env)"]:::config
        DataRetriever["Financial Data Retriever (simfin.py)"]:::module
        AI_OpenAI["AI Analysis Generator - OpenAI (openai.py)"]:::ai
        AI_Ollama["AI Analysis Generator - Ollama (ollama.py)"]:::ai
    end

    %% External Services
    subgraph "External Services"
        SimFinAPI["SimFin API"]:::external
        OpenAIAPI["OpenAI API"]:::external
        OllamaService["Ollama Service"]:::external
    end

    %% Data Flow
    CLI -->|"load_config"| Config
    CLI -->|"request_financial_data"| DataRetriever
    DataRetriever -->|"fetch_data"| SimFinAPI
    SimFinAPI -->|"return_data"| DataRetriever
    DataRetriever -->|"use_OpenAI_analysis"| AI_OpenAI
    DataRetriever -->|"use_Ollama_analysis"| AI_Ollama
    AI_OpenAI -->|"call_OpenAI_API"| OpenAIAPI
    OpenAIAPI -->|"return_analysis"| AI_OpenAI
    AI_Ollama -->|"call_Ollama_API"| OllamaService
    OllamaService -->|"return_analysis"| AI_Ollama
    AI_OpenAI -->|"deliver_analysis"| CLI
    AI_Ollama -->|"deliver_analysis"| CLI

    %% Click Events
    click CLI "https://github.com/austin-starks/finangpt/blob/master/chat.py"
    click CLI "https://github.com/austin-starks/finangpt/blob/master/main.py"
    click DataRetriever "https://github.com/austin-starks/finangpt/blob/master/simfin.py"
    click AI_OpenAI "https://github.com/austin-starks/finangpt/blob/master/openai.py"
    click AI_Ollama "https://github.com/austin-starks/finangpt/blob/master/ollama.py"

    %% Styles
    classDef cli fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef config fill:#ffeb99,stroke:#333,stroke-dasharray: 5, 5,stroke-width:2px;
    classDef module fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef ai fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef external fill:#d0f0c0,stroke:#333,stroke-width:2px;
```
