# urbao/stockoala architecture

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

- Interactive diagram: https://gitdiagram.com/urbao/stockoala
- Repository: https://github.com/urbao/stockoala

## Overview

##### Main Components
a. CLI Launcher
- run.sh (Linux) / stockoala.exe (Windows)
- stockoala.desktop (Linux desktop integration)
b. Configuration Loader
- src/config.py + src/config.json
c. Data Collector & Scraper
- src/collect.py
- src/stock_scraper.py (interacts with TWSE & TPEX via requests & bs4)
d. Data Storage (Local FS)
- weekly-data/ (text files)
- monthly-data/ (text + JSON files)
e. Data Combiner
- src/data_combiner.py (merges raw daily files into period aggregates)
f. Analyzers
- src/weekly_analyze.py (reverse‐point strategy)
- src/monthly_analyze.py (low‐price strategy)
- src/analyze.py + src/analyze_helper.py (common logic)
g. Output & Reporting
- src/output.py (console & file output)
h. Core Orchestrator
- src/main.py (invokes the above modules in sequence)

##### Relationships & Data Flows
– CLI Launcher invokes main.py
– main.py loads config → triggers collect → scraper fetches data → raw files written under weekly‐data/ & monthly‐data/
– data_combiner reads raw files → produces combined data structures
– analyzers consume combined data → compute signals
– output writes results to console or local report files

##### Architectural Patterns & Principles
- Modular layering: separate concerns for configuration, data collection, merging, analysis, and output.
- Local‐first storage: all data persists in file directories for privacy.
- Single‐process, script‐driven orchestration via Python CLI.

##### Incorporate Key Technologies
- Language & Runtime: Python 3.x
- HTTP & Parsing: requests, BeautifulSoup (bs4)
- CLI UX: colorama
- Shell Integration: Bash script & desktop entry (Linux)

– Arrowheads marking data direction (e.g., read vs. write)
– Annotations for protocols (e.g., HTTP GET to TWSE/TPEX)
– Boundaries: group all Python modules under a “Stockoala Core” boundary

## Diagram (Mermaid)

```mermaid
graph TB
    %% Launcher & Scheduler Layer
    subgraph "Launcher & Scheduler"
        direction TB
        RunSH["run.sh"]:::launcher
        Desktop["stockoala.desktop"]:::launcher
    end

    %% Configuration Layer
    subgraph "Configuration"
        direction TB
        ConfigPy["src/config.py"]:::compute
        ConfigJSON["src/config.json"]:::compute
    end

    %% Data Collection & Scraper Layer
    subgraph "Data Collection & Scraper"
        direction TB
        Collect["src/collect.py"]:::compute
        Scraper["src/stock_scraper.py"]:::compute
        ExternalAPIs["External APIs (TWSE & TPEX)"]:::external
    end

    %% Local Storage Layer
    subgraph "Local Storage"
        direction TB
        WeeklyStorage["weekly-data/"]:::storage
        MonthlyStorage["monthly-data/"]:::storage
    end

    %% Data Combiner Layer
    subgraph "Data Combiner"
        direction TB
        Combiner["src/data_combiner.py"]:::compute
    end

    %% Analysis Engines Layer
    subgraph "Analysis Engines"
        direction TB
        WeeklyAnalyzer["src/weekly_analyze.py"]:::compute
        MonthlyAnalyzer["src/monthly_analyze.py"]:::compute
        CommonAnalyze["src/analyze.py"]:::compute
        AnalyzeHelper["src/analyze_helper.py"]:::compute
    end

    %% Output & Reporting Layer
    subgraph "Output & Reporting"
        direction TB
        Output["src/output.py"]:::compute
    end

    %% Core Orchestrator
    subgraph "Stockoala Core"
        direction TB
        MainPy["src/main.py"]:::compute
    end

    %% Connections
    RunSH --> MainPy
    Desktop --> MainPy
    MainPy --> ConfigPy
    MainPy --> Collect
    ConfigPy --> Collect
    Collect --> Scraper
    Scraper -->|HTTP GET| ExternalAPIs
    Scraper --> WeeklyStorage
    Scraper --> MonthlyStorage
    WeeklyStorage --> Combiner
    MonthlyStorage --> Combiner
    Combiner --> WeeklyAnalyzer
    Combiner --> MonthlyAnalyzer
    WeeklyAnalyzer --> CommonAnalyze
    MonthlyAnalyzer --> CommonAnalyze
    CommonAnalyze --> AnalyzeHelper
    WeeklyAnalyzer --> Output
    MonthlyAnalyzer --> Output
    MainPy --> Output

    %% Click Events
    click RunSH "https://github.com/urbao/stockoala/blob/master/run.sh"
    click Desktop "https://github.com/urbao/stockoala/blob/master/stockoala.desktop"
    click ConfigPy "https://github.com/urbao/stockoala/blob/master/src/config.py"
    click ConfigJSON "https://github.com/urbao/stockoala/blob/master/src/config.json"
    click Collect "https://github.com/urbao/stockoala/blob/master/src/collect.py"
    click Scraper "https://github.com/urbao/stockoala/blob/master/src/stock_scraper.py"
    click WeeklyStorage "https://github.com/urbao/stockoala/tree/master/weekly-data/"
    click MonthlyStorage "https://github.com/urbao/stockoala/tree/master/monthly-data/"
    click Combiner "https://github.com/urbao/stockoala/blob/master/src/data_combiner.py"
    click WeeklyAnalyzer "https://github.com/urbao/stockoala/blob/master/src/weekly_analyze.py"
    click MonthlyAnalyzer "https://github.com/urbao/stockoala/blob/master/src/monthly_analyze.py"
    click CommonAnalyze "https://github.com/urbao/stockoala/blob/master/src/analyze.py"
    click AnalyzeHelper "https://github.com/urbao/stockoala/blob/master/src/analyze_helper.py"
    click Output "https://github.com/urbao/stockoala/blob/master/src/output.py"
    click MainPy "https://github.com/urbao/stockoala/blob/master/src/main.py"

    %% Styles
    classDef storage fill:#b2f2bb,stroke:#2a5934,color:#2a5934;
    classDef compute fill:#cce5ff,stroke:#3164a8,color:#3164a8;
    classDef external fill:#ffe5b4,stroke:#cc8400,color:#cc8400;
    classDef launcher fill:#e0e0e0,stroke:#767676,color:#333333;
```
