# basavaraj1985/screeni-py architecture

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

- Interactive diagram: https://gitdiagram.com/basavaraj1985/screeni-py
- Repository: https://github.com/basavaraj1985/screeni-py

## Overview

##### Project Type and Purpose
- Screeni-py is a Docker-packaged, Python-based stock-screening application for the NSE (India) that can be run via a Streamlit GUI or a legacy CLI. It fetches market data, applies technical-analysis and ML models, then renders results in a web UI (Streamlit) or exports to Excel/console.

##### High-Level File Structure Analysis
- Top-Level:
- Dockerfile, .dockerignore, Makefile – container build & run scripts
- requirements.txt, run_screenipy.sh – dependency and entrypoint scripts
- .github/workflows – CI for build, test, data-download
- actions-data-download – pre-downloaded data cache
- patterns – candle pattern definitions
- src/: core Python code
- src/screenipy.py – main orchestration CLI entrypoint
- src/streamlit_app.py + src/.streamlit – Streamlit GUI entrypoint & config
- src/classes/ – modular components (Fetcher, Screener, ConfigManager, OtaUpdater, ParallelProcessing, CandlePatterns, ScreenipyTA, Utility, SuppressOutput, Changelog, ColorText)
- src/ml/ – pretrained ML models (.h5, .pkl) and eval notebooks/scripts
- src/static/tablefilter/ – JavaScript/CSS assets for interactive tables
- src/screenipy.ini – user-editable config template
- test/: automated tests for core functionality

##### Key Components
A. User Interfaces (UI)
1. CLI Interface
- Entry: screenipy.py
- Interactive console or Excel export
2. Streamlit Web UI
- Entry: streamlit_app.py
- Static assets: tablefilter JS/CSS
B. Application Core (Business Logic)
- ConfigManager: loads/parses screenipy.ini
- OtaUpdater: checks/releases new versions
- Fetcher: retrieves or loads cached stock_data_*.pkl
- ParallelProcessing: orchestrates multi-threaded data downloads & computation
- Screener: applies CandlePatterns, TA-lib signals via ScreenipyTA
- Utility & ColorText / SuppressOutput / Changelog: support functions/logging
(Group under “Backend” – e.g., green)
C. Machine Learning Subsystem
- Stored models (nifty_model_v2/v3.h5/.pkl, best_model_0.7438acc.h5)
- Eval script (eval.py) for on-the-fly predictions
D. Data Layer
- External Data Source: NSE API or CSV downloads (GitHub action for data)
- Local Cache: actions-data-download/stock_data_*.pkl
- Configuration File: src/screenipy.ini
(“Data & Config” – orange)
E. Deployment & CI/CD
- Docker Container: encapsulates Python runtime, Streamlit server, scripts
- GitHub Actions: workflow-build-matrix.yml, workflow-test.yml, workflow-download-data.yml
(“Infrastructure” – gray)

##### Interactions and Data Flows
1. User → [CLI or Browser] → Entrypoint
2. Entrypoint → ConfigManager → loads parameters
3. Entrypoint → OtaUpdater (optional) → version check
4. Entrypoint → Fetcher → loads or refreshes market data
5. Fetcher ↔ External Data Source / Local Cache
6. Entrypoint → ParallelProcessing → dispatches Screener jobs
7. Screener → CandlePatterns + ScreenipyTA (TA-lib)
8. Screener → ML Engine (eval.py + model files)
9. Results → UI layer (Streamlit table via tablefilter.js/CSS or CLI console/Excel)
10. UI → renders to user
11. Docker Container wraps all, exposing ports 8501/8000

##### Architectural Patterns & Design Principles
- Modular, class-based separation of concerns (Fetcher vs. Screener vs. UI)
- Parallel processing to speed up I/O-bound & CPU-bound tasks
- Plugin-style integration of technical-analysis (TA-lib), pattern definitions, ML models
- Containerization for environment consistency and cross-platform support
- CI/CD pipelines automate testing, packaging, and data provisioning

## Diagram (Mermaid)

```mermaid
flowchart TD
    User(("User")):::external
    External(("NSE API/CSV")):::external
    GitHub(("GitHub Actions")):::infra
    DockerReg(("Docker Registry")):::infra

    User -->|"start screening"| CLI["CLI Interface"]:::ui
    User -->|"start screening"| Streamlit["Streamlit App"]:::ui

    subgraph "Docker Container"
        subgraph "UI Layer"
            CLI["CLI Interface"]:::ui
            Streamlit["Streamlit App"]:::ui
            Assets["tablefilter JS/CSS"]:::ui
            ConfigToml["Streamlit Config"]:::ui
        end
        subgraph "Backend Layer"
            ConfigManager["ConfigManager"]:::backend
            OtaUpdater["OtaUpdater"]:::backend
            Fetcher["Fetcher"]:::backend
            Parallel["ParallelProcessing"]:::backend
            Screener["Screener"]:::backend
            CandlePatterns["CandlePatterns"]:::backend
            TA["ScreenipyTA"]:::backend
            Utility["Utility"]:::backend
            ColorText["ColorText"]:::backend
            SuppressOutput["SuppressOutput"]:::backend
            Changelog["Changelog"]:::backend
        end
        subgraph "ML Engine"
            Eval["eval.py"]:::ml
            Model1["best_model_0.7438acc.h5"]:::ml
            Model2["nifty_model_v2.h5/.pkl"]:::ml
            Model3["nifty_model_v3.h5/.pkl"]:::ml
        end
        subgraph "Data & Config"
            ExternalCache["Local Cache"]:::data
            Ini["screenipy.ini"]:::data
        end
    end

    CLI -->|"load params"| ConfigManager
    Streamlit -->|"reads"| ConfigToml
    Streamlit -->|"uses assets"| Assets
    ConfigManager --> Ini
    CLI -->|"optional version check"| OtaUpdater
    CLI -->|"fetch data"| Fetcher
    Fetcher <-->|"load/cache"| ExternalCache
    Fetcher -->|"dispatch"| Parallel
    Parallel -->|"job"| Screener
    Screener -->|"patterns"| CandlePatterns
    Screener -->|"TA signals"| TA
    Screener -->|"ML predict"| Eval
    Eval --> Model1
    Eval --> Model2
    Eval --> Model3
    Screener --> Utility
    Screener --> ColorText
    Screener --> SuppressOutput
    Screener --> Changelog
    Screener -->|"return results"| CLI
    Screener -->|"return results"| Streamlit
    Streamlit -->|"render"| User
    CLI -->|"output"| User

    subgraph "CI/CD Pipeline"
        GitHub -->|"build/test/download-data"| DockerReg
        DockerReg -->|"pull image"| DockerContainer["Docker Container"]
    end

    click CLI "https://github.com/basavaraj1985/screeni-py/blob/main/src/screenipy.py"
    click Streamlit "https://github.com/basavaraj1985/screeni-py/blob/main/src/streamlit_app.py"
    click ConfigToml "https://github.com/basavaraj1985/screeni-py/blob/main/src/.streamlit/config.toml"
    click Assets "https://github.com/basavaraj1985/screeni-py/tree/main/src/static/tablefilter/"
    click ConfigManager "https://github.com/basavaraj1985/screeni-py/blob/main/src/classes/ConfigManager.py"
    click OtaUpdater "https://github.com/basavaraj1985/screeni-py/blob/main/src/classes/OtaUpdater.py"
    click Fetcher "https://github.com/basavaraj1985/screeni-py/blob/main/src/classes/Fetcher.py"
    click Parallel "https://github.com/basavaraj1985/screeni-py/blob/main/src/classes/ParallelProcessing.py"
    click Screener "https://github.com/basavaraj1985/screeni-py/blob/main/src/classes/Screener.py"
    click CandlePatterns "https://github.com/basavaraj1985/screeni-py/blob/main/src/classes/CandlePatterns.py"
    click TA "https://github.com/basavaraj1985/screeni-py/blob/main/src/classes/ScreenipyTA.py"
    click Utility "https://github.com/basavaraj1985/screeni-py/blob/main/src/classes/Utility.py"
    click ColorText "https://github.com/basavaraj1985/screeni-py/blob/main/src/classes/ColorText.py"
    click SuppressOutput "https://github.com/basavaraj1985/screeni-py/blob/main/src/classes/SuppressOutput.py"
    click Changelog "https://github.com/basavaraj1985/screeni-py/blob/main/src/classes/Changelog.py"
    click Eval "https://github.com/basavaraj1985/screeni-py/blob/main/src/ml/eval.py"
    click Model1 "https://github.com/basavaraj1985/screeni-py/blob/main/src/ml/best_model_0.7438acc.h5"
    click Model2 "https://github.com/basavaraj1985/screeni-py/blob/main/src/ml/nifty_model_v2.h5"
    click Model2 "https://github.com/basavaraj1985/screeni-py/blob/main/src/ml/nifty_model_v2.pkl"
    click Model3 "https://github.com/basavaraj1985/screeni-py/blob/main/src/ml/nifty_model_v3.h5"
    click Model3 "https://github.com/basavaraj1985/screeni-py/blob/main/src/ml/nifty_model_v3.pkl"
    click ExternalCache "https://github.com/basavaraj1985/screeni-py/blob/main/actions-data-download/stock_data_140823.pkl"
    click Ini "https://github.com/basavaraj1985/screeni-py/blob/main/src/screenipy.ini"
    click DockerContainer "https://github.com/basavaraj1985/screeni-py/tree/main/Dockerfile"
    click DockerContainer "https://github.com/basavaraj1985/screeni-py/blob/main/.dockerignore"
    click DockerContainer "https://github.com/basavaraj1985/screeni-py/tree/main/Makefile"
    click GitHub "https://github.com/basavaraj1985/screeni-py/blob/main/.github/workflows/workflow-build-matrix.yml"
    click GitHub "https://github.com/basavaraj1985/screeni-py/blob/main/.github/workflows/workflow-download-data.yml"
    click GitHub "https://github.com/basavaraj1985/screeni-py/blob/main/.github/workflows/workflow-test.yml"

    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#98FB98,stroke:#333,stroke-width:1px
    classDef ml fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#87CEEB,stroke:#333,stroke-width:1px
```
