# tamonashroy/price-prediction-app architecture

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

- Interactive diagram: https://gitdiagram.com/tamonashroy/price-prediction-app
- Repository: https://github.com/tamonashroy/price-prediction-app

## Overview

##### Project Type and Purpose
- This is a full-stack, batch-plus-web application for ingesting cryptocurrency price data, performing predictive modeling, and exposing analytics via a Streamlit dashboard.
- Key functions: ETL (Extract from CoinGecko), batch modeling and simulation, storage in SQLite, and a web UI.

##### File Structure
- Top-level orchestration and deployment:
- Dockerfile, `.devcontainer/*`, `.github/workflows/batch-and-push.yml`
- `.vscode` and `.devcontainer` for local/remote dev setups
- Core Python modules and scripts:
- Data ingestion: `ingest_coins.py`, `data_ingestion.py`, `fetch_coinswitch_coins.py`
- Database utilities: `db_utils.py`, `db_predictions.py`
- Modeling and batch prediction: `model.py`, `daily_batch_predict.py`, `batch_5day_predictions.csv`, etc.
- Simulation/analysis: `top5_daily_trade_simulation.py`, `populate_positions_from_top5.py`
- Web app: `app.py` (Streamlit) plus sidebar and helper modules (`coinswitch_sidebar_utils.py`, `coinswitch_utils.py`)
- Persistence:
- SQLite files: `coin_prices.db`, `coin_predictions.db` (or `predictions.sqlite`)
- CSV artifacts for reporting and testing
- Tests: `test_coinswith.py`
- Config/dependencies: `requirements.txt`, `.gitignore`

##### Extract Architecture Insights from the README
- Docker build and run encapsulate all components.
- The ingestion script writes to `coin_prices.db`.
- The Streamlit app (`app.py`) reads from the same mounted volume to surface analytics.
- Model training and prediction logic lives in `model.py` and auxiliary scripts, producing both DB updates and CSV exports.

##### Main Components
a. External Data Source:
- CoinGecko API (and optionally CoinSwitch via helper scripts)
b. Data Ingestion Layer:
- `ingest_coins.py` (ETL jobs)
- Helpers: `fetch_coinswitch_coins.py`, data-filtering scripts
c. Persistence Layer:
- SQLite instances (`coin_prices.db` for raw data, `coin_predictions.db` or `predictions.sqlite` for model outputs)
- CSV exports for batch reporting
d. Modeling & Batch Processing:
- `model.py` for feature engineering and training
- `daily_batch_predict.py` and other batch scripts to run predictions
e. Simulation & Analytics:
- Scripts like `top5_daily_trade_simulation.py`, `populate_positions_from_top5.py` that derive portfolio metrics
f. Web UI / Dashboard:
- Streamlit app (`app.py`) leveraging helper modules for layout and visualization
g. Deployment & CI/CD:
- Docker container wrapping all scripts and dependencies
- GitHub Actions workflow for builds (`.github/workflows/batch-and-push.yml`)

##### Relationships and Data Flows
1. CoinGecko API → Data Ingestion Layer
2. Ingestion Layer → `coin_prices.db`
3. `coin_prices.db` → Modeling Layer → `coin_predictions.db` + CSV reports
4. Prediction DB/CSVs → Streamlit UI
5. Optionally: Simulation scripts read both DBs → CSV outputs
- Trigger events: daily cron or manual run inside Docker

##### Architectural Patterns & Tech
- ETL pipeline for daily data refresh
- Batch-processing for prediction generation
- Monolithic Python codebase inside a single Docker image
- SQLite for lightweight persistence
- Streamlit for rapid dashboarding
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External Data Source"
        E1["CoinGecko API"]:::external
        E2["fetch_coinswitch_coins.py"]:::etl
        E3["filter_top5_green_coinswitch.py"]:::etl
    end

    subgraph "Data Ingestion Layer"
        D1["ingest_coins.py"]:::etl
        D2["data_ingestion.py"]:::etl
    end

    subgraph "Persistence Layer"
        DB1["coin_prices.db"]:::db
        DB2["coin_predictions.db"]:::db
        DB3["predictions.sqlite"]:::db
        CSV1["batch_5day_predictions.csv"]:::csv
        CSV2["batch_last5_actual_vs_predicted.csv"]:::csv
        CSV3["positions_actual_vs_predicted.csv"]:::csv
        CSV4["coinswitch_coin_mapping.csv"]:::csv
        CSV5["top5_coinswitch_5day_predictions.csv"]:::csv
    end

    subgraph "Modeling & Batch Processing"
        M1["model.py"]:::compute
        M2["daily_batch_predict.py"]:::compute
    end

    subgraph "Simulation & Analytics"
        S1["top5_daily_trade_simulation.py"]:::compute
        S2["populate_positions_from_top5.py"]:::compute
        S3["positions_actual_vs_predicted.py"]:::compute
    end

    subgraph "Web UI / Dashboard"
        W1["app.py"]:::ui
        W2["coinswitch_sidebar_utils.py"]:::ui
        W3["coinswitch_utils.py"]:::ui
    end

    subgraph "Deployment & CI/CD"
        C1["Dockerfile"]:::deploy
        C2[".github/workflows/batch-and-push.yml"]:::deploy
        C4[".devcontainer/devcontainer.json"]:::deploy
        C5[".vscode/"]:::deploy
        C6["requirements.txt"]:::deploy
        C7[".gitignore"]:::deploy
    end

    E1 -->|"requests"| D1
    E2 -->|"data for ETL"| D1
    E3 -->|"filtered data"| D1

    D1 -->|"writes raw data"| DB1
    D2 -->|"processes ingestion"| DB1

    DB1 -->|"raw data"| M1
    M1 -->|"predictions"| DB2
    M1 -->|"predictions"| DB3
    M2 -->|"batch predict"| DB2
    M2 -->|"export CSVs"| CSV1
    M2 -->|"export CSVs"| CSV2

    DB2 -->|"input for simulation"| S1
    DB2 -->|"input for simulation"| S2
    S1 -->|"simulation output"| CSV3
    S2 -->|"positions output"| CSV3

    CSV1 -->|"reports"| W1
    CSV2 -->|"reports"| W1
    DB2 -->|"read predictions"| W1
    DB1 -->|"read prices"| W1

    W1 -->|"layout helpers"| W2
    W1 -->|"logic helpers"| W3

    C1 -->|"containerizes"| D1
    C1 -->|"hosts UI"| W1
    C2 -->|"CI/CD triggers"| C1

    classDef external fill:#E8F1FF,stroke:#2C7BBF,color:#0D3B66;
    classDef etl fill:#FFF5E1,stroke:#E69A00,color:#994C00;
    classDef db fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20;
    classDef csv fill:#F3E5F5,stroke:#8E24AA,color:#4A148C;
    classDef compute fill:#E3F2FD,stroke:#1565C0,color:#0D47A1;
    classDef ui fill:#FFEBEE,stroke:#C62828,color:#B71C1C;
    classDef deploy fill:#ECEFF1,stroke:#455A64,color:#263238;

    click E2 "https://github.com/tamonashroy/price-prediction-app/blob/main/fetch_coinswitch_coins.py"
    click E3 "https://github.com/tamonashroy/price-prediction-app/blob/main/filter_top5_green_coinswitch.py"
    click D1 "https://github.com/tamonashroy/price-prediction-app/blob/main/ingest_coins.py"
    click D2 "https://github.com/tamonashroy/price-prediction-app/blob/main/data_ingestion.py"
    click DB1 "https://github.com/tamonashroy/price-prediction-app/blob/main/coin_prices.db"
    click DB2 "https://github.com/tamonashroy/price-prediction-app/blob/main/coin_predictions.db"
    click DB3 "https://github.com/tamonashroy/price-prediction-app/blob/main/predictions.sqlite"
    click CSV1 "https://github.com/tamonashroy/price-prediction-app/blob/main/batch_5day_predictions.csv"
    click CSV2 "https://github.com/tamonashroy/price-prediction-app/blob/main/batch_last5_actual_vs_predicted.csv"
    click CSV3 "https://github.com/tamonashroy/price-prediction-app/blob/main/positions_actual_vs_predicted.csv"
    click CSV4 "https://github.com/tamonashroy/price-prediction-app/blob/main/coinswitch_coin_mapping.csv"
    click CSV5 "https://github.com/tamonashroy/price-prediction-app/blob/main/top5_coinswitch_5day_predictions.csv"
    click M1 "https://github.com/tamonashroy/price-prediction-app/blob/main/model.py"
    click M2 "https://github.com/tamonashroy/price-prediction-app/blob/main/daily_batch_predict.py"
    click S1 "https://github.com/tamonashroy/price-prediction-app/blob/main/top5_daily_trade_simulation.py"
    click S2 "https://github.com/tamonashroy/price-prediction-app/blob/main/populate_positions_from_top5.py"
    click S3 "https://github.com/tamonashroy/price-prediction-app/blob/main/positions_actual_vs_predicted.py"
    click W1 "https://github.com/tamonashroy/price-prediction-app/blob/main/app.py"
    click W2 "https://github.com/tamonashroy/price-prediction-app/blob/main/coinswitch_sidebar_utils.py"
    click W3 "https://github.com/tamonashroy/price-prediction-app/blob/main/coinswitch_utils.py"
    click C1 "https://github.com/tamonashroy/price-prediction-app/tree/main/Dockerfile"
    click C2 "https://github.com/tamonashroy/price-prediction-app/blob/main/.github/workflows/batch-and-push.yml"
    click C4 "https://github.com/tamonashroy/price-prediction-app/blob/main/.devcontainer/devcontainer.json"
    click C5 "https://github.com/tamonashroy/price-prediction-app/tree/main/.vscode/"
    click C6 "https://github.com/tamonashroy/price-prediction-app/blob/main/requirements.txt"
    click C7 "https://github.com/tamonashroy/price-prediction-app/blob/main/.gitignore"
```
