# bcdannyboy/ttontt architecture

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

- Interactive diagram: https://gitdiagram.com/bcdannyboy/ttontt
- Repository: https://github.com/bcdannyboy/ttontt

## Overview

##### Main Components
- Input/Configuration: • • A ticker definition file (tickers.py) that lists the stocks to analyze.
- Orchestration/Coordinator: • metal_coordinator.py or ttontt.py that serves as the main execution script and coordinates the workflow.
- Fundamental Analysis Module: • Located in src/screener/fundamentals with files (e.g., fundamentals_core.py, fundamentals_data.py, fundamentals_report.py) which calculate various financial ratios, growth indicators, and perform peer comparisons.
- Technical Analysis Module: • Found in src/screener/technical with files to compute indicators (e.g., indicator_extraction.py, scoring.py, screening.py) such as SMA, EMA, MACD, RSI, and more.
- Simulation Module: • Under src/simulation with modules for Monte Carlo simulations (montecarlo.py), parallel processing, model evaluation, and visualization.
- Volatility Module: • In src/volatility for historical volatility analysis.
- Caching System: • Although not an explicit directory, the README describes memory and disk caching strategies (with TTL, separate cache for metrics) that interact with data retrieval.
- External Data Services: • Represent the OpenBB SDK integration and Financial Modeling Prep (FMP) API for financial data.

##### Out Relationships and Data Flow
- Ticker Input (tickers.py) provides the list of stocks and initiates the analysis.
- The main coordinator script (metal_coordinator.py or ttontt.py) triggers the data pipelines.
- Analysis Workflow: • Fundamental Analysis fetches and processes data into various metrics and generates reports; similarly, Technical Analysis computes indicators that inform trading signals.
- Subsequent Simulation: • Results from both screening processes feed into the Simulation Module (montecarlo.py and other simulation scripts) to project potential outcomes.
- Volatility Module: • Can branch off from technical analysis to compute historical volatility metrics.
- Output: • Finally, the processed results lead to two outputs:
- JSON files saved in an “output” directory (e.g., fundamental_screening_[timestamp].json)

##### Important Architectural Patterns and Design Principles
- Modular Design: • The system is broken into clear functional modules (screener, simulation, volatility) that encapsulate distinct analytical functions.
- Separation of Concerns: • Divide the responsibilities distinctly (data retrieval, screening, simulation, and reporting).
- Integration with External Services: • Emphasize the dependency on OpenBB and the FMP API for data, and show this interaction clearly.
- Caching Strategy: • Illustrate how the caching layer is positioned to enhance performance, reduce API calls, and serve as a fallback.

##### Technologies and Frameworks
- Python is the primary language.
- Use of OpenBB SDK for data retrieval.
- Financial Modeling Prep API for live data needs.
- Monte Carlo and statistical libraries for simulation purposes.
- JSON for output reports containing analysis results.

##### Final Recommendations
- Be as detailed as possible; map every module in src (screener with its submodules, simulation, volatility) and link them logically.
- Interplay between external data sources and internal caching to underscore performance and reliability.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Input/Configuration
    TickerInput["Ticker Definition (tickers.py)"]:::internal

    %% Orchestration/Coordinator Subgraph
    subgraph "Coordinator"
        MC["metal_coordinator.py"]:::internal
        TT["ttontt.py"]:::internal
    end

    %% Analysis Modules Subgraph
    subgraph "Analysis Modules"
        FAM["Fundamental Analysis Module"]:::internal
        TAM["Technical Analysis Module"]:::internal
        VM["Volatility Module"]:::internal
    end

    %% External Data Services Subgraph
    subgraph "External Data Services"
        OBB["OpenBB SDK"]:::external
        FMP["FMP API"]:::external
    end

    %% Cache Layer Subgraph
    subgraph "Cache Layer"
        MCACH["Memory Cache"]:::cache
        DCACH["Disk Cache"]:::cache
    end

    %% Simulation Module
    subgraph "Simulation"
        SIM["Simulation Module"]:::internal
    end

    %% Output Subgraph
    subgraph "Output"
        CON["Console Output"]:::output
        JSON["JSON Files Output"]:::output
    end

    %% Data Flow
    TickerInput --> MC
    TickerInput --> TT

    MC --> FAM
    MC --> TAM
    TT --> FAM
    TT --> TAM

    TAM --> VM

    FAM --> OBB
    FAM --> FMP
    TAM --> OBB
    TAM --> FMP

    FAM <--> MCACH
    FAM <--> DCACH
    TAM <--> MCACH
    TAM <--> DCACH

    FAM --> SIM
    TAM --> SIM
    VM --> SIM

    SIM --> CON
    SIM --> JSON

    %% Legend
    subgraph "Legend"
        L1["Internal Module (Blue)"]
        L2["External Service (Green)"]
        L3["Cache Component (Orange)"]
        L4["Output (Purple)"]
    end

    %% Click Events
    click TickerInput "https://github.com/bcdannyboy/ttontt/blob/main/tickers.py"
    click MC "https://github.com/bcdannyboy/ttontt/blob/main/metal_coordinator.py"
    click TT "https://github.com/bcdannyboy/ttontt/blob/main/ttontt.py"
    click FAM "https://github.com/bcdannyboy/ttontt/tree/main/src/screener/fundamentals"
    click TAM "https://github.com/bcdannyboy/ttontt/tree/main/src/screener/technical"
    click SIM "https://github.com/bcdannyboy/ttontt/tree/main/src/simulation"
    click VM "https://github.com/bcdannyboy/ttontt/blob/main/src/volatility/historical.py"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef external fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef cache fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef output fill:#DDA0DD,stroke:#000,stroke-width:2px;
```
