# ruheil/ml-codestacker architecture

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

- Interactive diagram: https://gitdiagram.com/ruheil/ml-codestacker
- Repository: https://github.com/ruheil/ml-codestacker

## Overview

##### Project Type & Main Purpose
- The application is a full-stack, data analytics dashboard (with a focus on visualization and classification).
- The system analyzes crime data from a CSV file, processes police report PDFs, performs crime prediction and classification (using a pre-trained or dynamically generated model from crime_classifier.joblib), and presents multiple dashboard modules via Streamlit.

##### File Structure
- Top-level files like app.py, Competition_Dataset.csv, crime_classifier.joblib, and requirements.txt reveal that the app serves as both the UI and the processing backend.
- Dockerfile and .dockerignore indicate containerized deployment is supported.
- The notebook (lvl1 & lvl2.ipynb) is likely used for exploratory analysis or prototyping and can be noted as part of the development/analysis tools.
- README.md provides clear use-case details and deployment instructions.

##### Main Components to Capture
a. User Interface / Presentation Layer:
- Streamlit application (app.py) as the central UI component through which users interact with the dashboard.

b. Data Ingestion & Processing Layer:
- CSV file (Competition_Dataset.csv) as the primary data source.
- A component for data preprocessing (extraction of timestamps, coordinates, and severity levels).
- Handling of PDF police reports for report processing.

c. Machine Learning / Prediction Component:
- Crime classification module that either loads a pre-trained model (crime_classifier.joblib) or creates a model on demand.
- Flow from user input (crime descriptions) to the prediction engine.

d. Dashboard Modules (sub-components within the UI):
- Crime Analytics: Temporal, categorical, and severity analysis.
- Report Processing: PDF uploads and extraction of key report info.
- Prediction & Classification: User input transformation to predicted crime types and severity.
- Geospatial Analysis: Interactive mapping, including heat maps, cluster maps, etc.

e. Deployment & Infrastructure Layer:
- Docker containerization (Dockerfile) to show how the app is deployed.
- Optionally, denote cloud deployment steps (e.g., use of Streamlit Community Cloud or other cloud providers).

##### Interrelationships and Data Flow
- Data acquisition (from CSV and user-uploaded PDFs) flowing into the Data Processing component.
- Direct the processed data toward the various dashboard modules (analytical visualizations, predictive modeling, geospatial mapping).
- User requests (clicks/inputs in the UI) being sent to the relevant processing modules, which then update the dashboard.
- That the ML model is accessed by both the prediction and report processing modules.

##### Architectural Patterns and Design Principles
- Modular design: Separate components for data ingestion, processing, ML prediction, and visualization.
- Loose coupling: Components for ML, PDF processing, and visualization should communicate via clear interfaces (with app.py coordinating overall actions).
- Containerization and deployment best practices: emphasize Docker’s role in packaging the application for scalable deployment.
- That even though it’s a single-file (app.py) Streamlit application, logically decomposing the functionality improves clarity for the system design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["User"]
    B["Streamlit UI (app.py)"]:::ui
    C["Crime Data Source (CSV Input)"]:::data
    N["User Uploaded PDFs"]:::data
    D["Data Preprocessing"]:::process
    D1["PDF Report Processor"]:::process
    E["Machine Learning Prediction Component (crime_classifier.joblib)"]:::ml
    subgraph "Dashboard Modules"
        F["Crime Analytics"]:::ui
        G["Report Processing"]:::ui
        H["Prediction & Classification"]:::ui
        I["Geospatial Analysis"]:::ui
    end
    J["Exploratory Data Analysis (lvl1 & lvl2.ipynb)"]:::analysis
    K["Containerized Deployment (Dockerfile)"]:::deploy
    L["Dependency & Setup (requirements.txt, README.md)"]:::deploy
    M["Cloud Deployment"]:::deploy

    A -->|"interacts"| B
    C -->|"CSV_input"| D
    N -->|"PDF_input"| D1
    J -->|"analysis_data"| D
    D -->|"processed_data"| E
    D1 -->|"extracted_info"| E
    E -->|"classification"| H
    B -->|"renders"| F
    B -->|"renders"| G
    B -->|"renders"| H
    B -->|"renders"| I
    L -->|"dependency_installed_for"| B
    B -->|"packaged_in"| K
    K -->|"deployed_to"| M

    click B "https://github.com/ruheil/ml-codestacker/blob/main/app.py"
    click C "https://github.com/ruheil/ml-codestacker/blob/main/Competition_Dataset.csv"
    click E "https://github.com/ruheil/ml-codestacker/blob/main/crime_classifier.joblib"
    click J "https://github.com/ruheil/ml-codestacker/blob/main/lvl1 & lvl2.ipynb"
    click K "https://github.com/ruheil/ml-codestacker/tree/main/Dockerfile"
    click L "https://github.com/ruheil/ml-codestacker/blob/main/requirements.txt"

    classDef ui fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef data fill:#ABEBC6,stroke:#239B56,stroke-width:2px;
    classDef process fill:#F9E79F,stroke:#F4D03F,stroke-width:2px;
    classDef ml fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
    classDef deploy fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef analysis fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
```
