How zweack/cricnotifier works
Project Type and Purpose
• This is a Python-based, CLI application (“cricNotifier”) that fetches real-time cricket data from an external API and displays it in the terminal and via OS notifications.
• It is packaged as a PyPI module (pyproject.toml, requirements.txt) and includes CI workflows for testing and publishing.
File Structure
• Top level:
• .github/workflows/ → CI pipelines (python‐app.yml, python‐package.yml)
• cricNotifier/ → source package
• tests/ → pytest test suite
• pyproject.toml & requirements.txt → dependency definitions
• Inside cricNotifier/:
• main.py → CLI entrypoint and command dispatcher
• __init__.py → package init
• static/ → assets for notifications
• Test folder targets core functionality (e.g., test_scoreboard.py).
README Insights
• Describes commands (list, select, info, squad, score, commentary)
• Notes cross-platform notifications (Linux via dbus-python, Windows via platform APIs)
• Emphasizes a “rich command line interface” (likely uses libraries such as rich, click or argparse).
a. Main Components
1. CLI Layer
– Parses user commands, flags, and options
– Delegates to the Core Service
2. Core Service Layer
– Implements business logic for each command (list, select, info, etc.)
– Maintains local cache of selected match ID (in memory or file)
3. Data Access Layer (API Client)
– Makes HTTP requests to the external cricket data API
– Handles authentication, error retry, JSON parsing
4. Notification Service
– Wraps OS notification APIs (dbus-python on Linux, WinRT or plyer on Windows)
5. Presentation Layer
– Renders tabular output in terminal (e.g., via rich.table)
6. External Cricket Data API
– Third-party REST endpoints providing match lists, scores, commentary
7. CI/CD Pipelines
– GitHub Actions workflows for running tests and publishing packages
b. Relationships & Interactions
– User types a cricNotifier command → CLI Layer → invokes Core Service.
– Core Service calls Data Access Layer → HTTP request → External API.
– API returns JSON → Data Access Layer → Core Service processes it.
– Core Service updates local cache if needed.
– Core Service sends data to Presentation Layer for terminal output.
– Core Service sends notifications payload to Notification Service → OS API.
– CI/CD pipelines monitor repo → run tests → build & publish package.
c. Architectural Patterns & Principles
– Layered Monolith: clear separation between CLI, business logic, data access, and notifications.
– Single Responsibility: each module (CLI parser, API client, notifier) has a focused role.
– Dependency Inversion: high-level Core Service depends on abstracted API client and notifier interfaces.
– Cross-platform abstraction for notifications.
d. Key Technologies & Frameworks
– Python 3.x
– HTTP client (e.g., requests or httpx)
– CLI parsing (click or argparse)
– Rich terminal output (rich)
– dbus-python (Linux notifications), Windows notification library
– pytest for tests
– GitHub Actions for CI/CD
Detailed Capture of Essential Architecture
• Interfaces between layers (e.g., “HTTP/JSON,” “DBus API,” “Stdout/Rich Table”).
• Optionally, include a note on where tests hook into the Core Service and API Client for mocking.
• CI workflows as a separate lane that pulls from the GitHub repository and outputs a distributed package.