# zweack/cricnotifier architecture

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

- Interactive diagram: https://gitdiagram.com/zweack/cricnotifier
- Repository: https://github.com/zweack/cricnotifier

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Internal Modules
    subgraph "Internal Modules"
        subgraph "CLI Layer"
            CLI["CLI Parser"]:::internal
        end
        subgraph "Core Service Layer"
            Core["Core Service"]:::internal
        end
        subgraph "Data Access Layer"
            APIClient["API Client\n(HTTP/JSON)"]:::internal
        end
        subgraph "Presentation Layer"
            Presentation["Rich Output Renderer"]:::internal
        end
        subgraph "Notification Service"
            Notify["OS Notification Service"]:::internal
        end
    end

    %% External Systems
    subgraph "External Systems"
        ExtAPI["External Cricket Data API"]:::external
        OSAPI["OS Notification API"]:::external
        User(["User"]):::external
        PyPI(["PyPI"]):::external
    end

    %% Infrastructure
    subgraph "Infrastructure & CI/CD"
        CIApp["CI Pipeline\n(python-app.yml)"]:::infra
        CIPkg["CI Pipeline\n(python-package.yml)"]:::infra
        Tests["Test Suite\n(test_scoreboard.py)"]:::infra
        Deps1["pyproject.toml"]:::infra
        Deps2["requirements.txt"]:::infra
    end

    %% Data Flows
    User -->|types command| CLI
    CLI -->|invokes| Core
    Core -->|HTTP/JSON| APIClient
    APIClient -->|REST Request| ExtAPI
    ExtAPI -->|JSON Response| APIClient
    APIClient -->|data| Core
    Core -->|render| Presentation
    Core -->|notify payload| Notify
    Notify -->|calls| OSAPI

    %% CI/CD Flows
    Deps1 --> CIApp
    Deps2 --> CIApp
    Tests --> CIApp
    Deps1 --> CIPkg
    Deps2 --> CIPkg
    CIApp -->|runs tests| Tests
    CIApp -->|builds/publishes| PyPI
    CIPkg -->|publishes| PyPI

    %% Test Hooks
    Tests -->|mocks| Core
    Tests -->|mocks| APIClient

    %% Click Events
    click CLI "https://github.com/zweack/cricnotifier/blob/dev/cricNotifier/main.py"
    click Core "https://github.com/zweack/cricnotifier/blob/dev/cricNotifier/__init__.py"
    click Notify "https://github.com/zweack/cricnotifier/tree/dev/cricNotifier/static/icon"
    click Presentation "https://github.com/zweack/cricnotifier/blob/dev/cricNotifier/main.py"
    click CIApp "https://github.com/zweack/cricnotifier/blob/dev/.github/workflows/python-app.yml"
    click CIPkg "https://github.com/zweack/cricnotifier/blob/dev/.github/workflows/python-package.yml"
    click Tests "https://github.com/zweack/cricnotifier/blob/dev/tests/test_scoreboard.py"
    click Deps1 "https://github.com/zweack/cricnotifier/blob/dev/pyproject.toml"
    click Deps2 "https://github.com/zweack/cricnotifier/blob/dev/requirements.txt"

    %% Styles
    classDef internal fill:#b8f2e6,stroke:#333,stroke-width:1px
    classDef external fill:#ade8f4,stroke:#333,stroke-width:1px
    classDef infra fill:#e0e0e0,stroke:#333,stroke-width:1px
```
