# nitheesh-14/leetcode_stats_generator architecture

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

- Interactive diagram: https://gitdiagram.com/nitheesh-14/leetcode_stats_generator
- Repository: https://github.com/nitheesh-14/leetcode_stats_generator

## Overview

##### What this project is (type + purpose)

From the README + file tree, this is a **desktop application** built with **Python + Flask + PyWebView** that:

- Hosts a **local Flask web app** (UI + endpoints)
- Wraps it into a **Windows desktop executable** via **PyWebView**
- Fetches **LeetCode user stats** (real-time), aggregates/filters by time windows (Today/Yesterday/Last Week/All Time)
- Renders a **centralized dashboard**
- Exports **WYSIWYG Excel reports**
- Sends **bulk email reports** via Gmail/App Passwords
- Stores configuration locally (e.g., `config.json` created at runtime; `.env.example` suggests env-based config too)

##### How the repo structure maps to architecture

Top-level:

- `app.py`
Likely the **Flask app entrypoint**: routes, request handling, wiring to services in `utils/`, template rendering, export/email endpoints, reading/writing local config.
- `templates/` (`dashboard.html`, `setup.html`)
The **server-rendered UI** (Flask + Jinja templates). Setup wizard suggests first-run configuration flow.
- `static/`
UI assets (CSS/JS/images like `ls_logo.png`), “hacker-themed UI”.
- `utils/`
This is your internal “service layer” / application logic:
- `fetch_data.py` → LeetCode scraping/API calls, network client
- `process_data.py` → aggregation + time filtering logic
- `stats_service.py` → likely orchestration/facade used by routes: “get stats for N users and time window”
- `email_report.py` → Gmail SMTP / Gmail API integration, composing/sending emails
- `.env.example`
Indicates configurable secrets/params (email creds, etc.). Even if the app uses `config.json`, show both as possible config sources.
- `templates/setup.html` + README mention of `config.json`
Implies a local persistence component (simple file-based storage).

This is effectively a **modular monolith**: one process, multiple internal modules, external calls out.

##### Windows Desktop Shell (PyWebView)
- Hosts an embedded browser window
- Points to `http://127.0.0.1:<port>` served by Flask

##### Local Flask Server (`app.py`)
- Route handlers (setup, dashboard, export, email)
- Serves HTML templates + static assets
- Calls into `utils/*` modules

##### UI Layer (Templates + Static)
- `templates/setup.html`
- `templates/dashboard.html`
- `static/*` assets
- User interactions: choose time filter, export, send email, settings

##### Stats Orchestration Service (`utils/stats_service.py`)
- Central boundary: “get batch stats(view=Today/Yesterday/…)”
- Calls fetch + process modules

##### LeetCode Data Fetcher (`utils/fetch_data.py`)
- External HTTP requests to LeetCode endpoints
- Error handling, rate limits (even if not explicit, mark “network dependency”)

##### Data Processing/Aggregation (`utils/process_data.py`)
- Compute totals, deltas, per-time-window metrics
- Prepare “dashboard view model” + “export model”

##### Export Generator (likely in `app.py` or `utils/process_data.py`)
- WYSIWYG column inclusion logic

##### Email Reporting (`utils/email_report.py`)
- Composes messages + attachments (Excel)
- Sends via Gmail (SMTP or API)

##### Local Persistence / Configuration
- `config.json` (runtime-created)
- optional `.env` usage
- Stores: usernames list, Gmail app password, preferences

##### External Systems
- **LeetCode** (data source)
- **Gmail** (email delivery)

##### Flow 1: First-run setup (Setup Wizard)
- User → PyWebView UI → Flask `/setup` route
- Flask reads/writes **Local Config (`config.json`)**
- After config saved → redirect to `/dashboard`

- UI → Flask: “POST usernames + email settings”
- Flask → Local Config: “persist settings”

##### Flow 2: Dashboard load + time filters
- User selects time filter (Today/Yesterday/Last Week/All Time)
- UI sends request → Flask route (e.g., `/dashboard?range=today`)
- Flask calls `stats_service.get_stats(range, users)`
- `stats_service` calls:
- `fetch_data` (for each username) → LeetCode
- `process_data` → aggregates + filters
- Flask renders `dashboard.html` with computed stats

- Flask → Stats Service → Fetch Data → LeetCode
- Fetch Data → Stats Service → Process Data → Stats Service → Flask
- Flask → Templates: “render view model”

##### Flow 3: Excel export (WYSIWYG)
- User clicks Export
- UI → Flask `/export` with current view state (visible columns + time range)
- Flask/Export module uses processed dataset to generate Excel
- Returns file download to UI

- UI → Flask: “export request + view state”
- Flask → Export Generator: “produce .xlsx”
- Flask → UI: “download”

##### Flow 4: Bulk email report
- User clicks Send Email
- UI → Flask `/email/send`
- Flask → `email_report` (compose + attach Excel)
- `email_report` → Gmail (SMTP/API)
- Status returned to UI

- Flask → Email Report → Gmail
- Gmail → Email Report: “delivery result”
- Flask → UI: “success/failure”

- External entities: Mentor/User, LeetCode, Gmail
- Purpose: show who uses it and what it integrates with

Inside “Desktop App”, show:
- PyWebView desktop shell
- Local Flask server
- Local filesystem config store
- External services (LeetCode, Gmail)

This captures the most important architectural truth: **it’s not a cloud app**—everything runs locally.

Inside “Flask Server” show:
- Route/controller layer (in `app.py`)
- `stats_service`
- `fetch_data`
- `process_data`
- `email_report`
- Export module
- Template rendering + static serving

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Context (C4 L1)
%% =========================
subgraph "Context (C4 Level 1)"
direction TB
User["Mentor/User"]:::external

AppCtx["LeetCode Stats Generator<br/>Desktop App (Windows)"]:::container

LeetCode["LeetCode<br/>(External Data Source)"]:::external
Gmail["Gmail<br/>(Email Delivery)"]:::external

User -->|"uses"| AppCtx
AppCtx -->|"fetches_stats"| LeetCode
AppCtx -->|"sends_bulk_reports"| Gmail
end

%% =========================
%% Containers (C4 L2)
%% =========================
subgraph "Containers (C4 Level 2) — Runs Locally on Windows"
direction TB

subgraph "Windows Desktop App Boundary"
direction TB

PyWebView["PyWebView Desktop Shell<br/>(Embedded Browser Window)"]:::runtime
Flask["Local Flask Server<br/>(Routes + Controllers)"]:::runtime

subgraph "UI Layer"
direction TB
Templates["Jinja Templates<br/>(setup.html, dashboard.html)"]:::ui
Static["Static Assets<br/>(CSS/JS/Images)"]:::ui
end

Config[("Local Config Store<br/>(config.json + .env)")]:::persistence

PyWebView <-->|"HTTP_localhost"| Flask
Flask -->|"renders"| Templates
Flask -->|"serves"| Static
Flask <-->|"read_write_JSON"| Config

end
end

%% External calls from local containers
Flask -->|"HTTPS_requests"| LeetCode
Flask -->|"SMTP_or_API"| Gmail

%% =========================
%% Components (C4 L3) - Flask App Internals
%% =========================
subgraph "Components (C4 Level 3) — Inside Flask Server"
direction TB

Routes["Route Handlers<br/>(/setup, /dashboard, /export, /email/send)"]:::runtime

StatsSvc["Stats Orchestrator<br/>(Facade: get_stats(range, users))"]:::service
Fetcher["LeetCode Fetcher<br/>(HTTP client / scrape / API)"]:::service
Processor["Processor<br/>(Aggregation + Time Windows)"]:::service

Export["Excel Export Generator<br/>(WYSIWYG .xlsx)"]:::service
Emailer["Email Reporter<br/>(Compose + Attach + Send)"]:::service

LocalFS[("Local Filesystem<br/>(temp .xlsx)")]:::persistence

Routes -->|"calls"| StatsSvc
StatsSvc -->|"fetch_per_user"| Fetcher
Fetcher -->|"HTTPS_scrape_API"| LeetCode
StatsSvc -->|"aggregate_filter"| Processor
Processor -->|"view_model"| Routes

Routes -->|"generate_XLSX"| Export
Export -->|"write_temp_file"| LocalFS
Routes -->|"download_response"| PyWebView

Routes -->|"send_report"| Emailer
Emailer -->|"attach_XLSX"| LocalFS
Emailer -->|"SMTP_or_API_send"| Gmail
Gmail -->|"delivery_result"| Emailer
Emailer -->|"status"| Routes

Routes <-->|"load_save_settings"| Config
end

%% Map Flask node to its internal components
Flask -->|"contains"| Routes

%% =========================
%% User Journeys (Annotated Triggers)
%% =========================
User -->|"first_run_setup: POST(usernames,email_settings)"| PyWebView
PyWebView -->|"setup_submit"| Flask
Flask -->|"persist_settings"| Config

User -->|"dashboard_load: GET(range=today|yesterday|week|all)"| PyWebView
PyWebView -->|"request_stats"| Flask

User -->|"export_click: POST(view_state,range,columns)"| PyWebView
User -->|"send_email_click: POST(recipients,range,attachment)"| PyWebView

%% =========================
%% Add EnvExample node (kept near config)
%% =========================
EnvExample["Environment Template<br/>(.env.example)"]:::persistence
EnvExample -.->|"example_values"| Config

%% =========================
%% Click Events (from component_mapping)
%% =========================
click Flask "https://github.com/nitheesh-14/leetcode_stats_generator/blob/main/app.py"
click Routes "https://github.com/nitheesh-14/leetcode_stats_generator/blob/main/app.py"
click Templates "https://github.com/nitheesh-14/leetcode_stats_generator/blob/main/templates/dashboard.html"
click Static "https://github.com/nitheesh-14/leetcode_stats_generator/tree/main/static/"
click StatsSvc "https://github.com/nitheesh-14/leetcode_stats_generator/blob/main/utils/stats_service.py"
click Fetcher "https://github.com/nitheesh-14/leetcode_stats_generator/blob/main/utils/fetch_data.py"
click Processor "https://github.com/nitheesh-14/leetcode_stats_generator/blob/main/utils/process_data.py"
click Emailer "https://github.com/nitheesh-14/leetcode_stats_generator/blob/main/utils/email_report.py"
click EnvExample "https://github.com/nitheesh-14/leetcode_stats_generator/blob/main/.env.example"

%% =========================
%% Styles
%% =========================
classDef container fill:#1f4b99,stroke:#0b2557,color:#ffffff,stroke-width:2px;
classDef runtime fill:#2b6cb0,stroke:#1a365d,color:#ffffff,stroke-width:1.5px;
classDef service fill:#2c5282,stroke:#1a365d,color:#ffffff,stroke-width:1.5px;
classDef ui fill:#2f855a,stroke:#1f5f3f,color:#ffffff,stroke-width:1.5px;
classDef persistence fill:#c05621,stroke:#7b341e,color:#ffffff,stroke-width:1.5px;
classDef external fill:#9b2c2c,stroke:#63171b,color:#ffffff,stroke-width:2px;
```
