How nitheesh-14/leetcode_stats_generator works
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