# ismailbenhallam/moroccan-prayer-times architecture

> Architecture diagram of the GitHub repository ismailbenhallam/moroccan-prayer-times, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ismailbenhallam/moroccan-prayer-times
- Repository: https://github.com/ismailbenhallam/moroccan-prayer-times

## Overview

##### Project type and purpose
- This is an open-source, Python-based command-line application (CLI) that fetches Moroccan prayer times from the official Ministry of Habous and Islamic Affairs website.
- It provides commands to show today’s times, time until next prayer, and to configure city and language. It also caches responses and supports localization (AR/EN/FR).

##### File structure
- Top-level files and folders
– `.github/workflows/pypi-publish.yml`: CI/CD pipeline for publishing to PyPI
– `setup.py`, `MANIFEST.in`, `requirements.txt`: packaging and dependency configuration
– `README.md`, `LICENSE`: documentation and licensing
- Package folder `moroccan_prayer_times/`
– `main.py`: CLI entry point (defines commands: next, today, config, setup)
– `__init__.py`: package initializer
– `translations/`: YAML files (`ar.yml`, `en.yml`, `fr.yml`) for localization
- No frontend or database subdirectories: single-process CLI tool

##### Extract key architectural insights from README
- External dependency: Ministry website HTTP API
- Local caching mechanism for performance
- Configuration persisted locally (city, language)
- Localization layer to format UI in selected language
- Packaging for pip/pipx installation
- CI workflow for automated PyPI publishing

##### Main components and their interactions
a. User (terminal)
↳ invokes the CLI command (`prayertime next`, etc.)
b. CLI layer (`main.py`)
↳ parses arguments, dispatches to core functions
c. Configuration module (persistent file, e.g., JSON/YAML)
↳ reads/writes user preferences (city, language)
d. Cache module (local file or in-memory)
↳ stores last-fetched prayer times with timestamp
e. HTTP client module
↳ issues GET request to Ministry website, handles errors
f. Parser module
↳ extracts prayer time data from HTTP response (HTML or JSON)
g. Localization module
↳ loads correct `translations/*.yml` file and formats labels
h. Output module
↳ renders data to terminal (with appropriate encoding/font for Arabic)
i. CI/CD pipeline (GitHub Actions)
↳ runs tests (if any), builds package, publishes to PyPI

##### Architectural patterns and design principles
- Modular separation of concerns: CLI vs. config vs. HTTP vs. parsing vs. localization vs. output
- Single-process, synchronous flow (could evolve to async HTTP calls)
- Pluggable translations (YAML-backed)
- Local caching for resiliency and reduced HTTP traffic
- Clean package boundary for easy pip installation

##### Additional notes
- Python runtime / environment boundary (user’s machine)
- How pipx installs a shim that invokes the package’s entry point

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["Terminal User"]:::external

    %% Application Boundary
    subgraph "Python CLI Application"
        direction TB
        CLI["CLI Layer\n(main.py)"]:::cli
        PackageInit["Package Init\n(__init__.py)"]:::core
        Config["Config Store"]:::core
        Cache["Cache Module"]:::core
        HTTP["HTTP Client"]:::core
        Parser["Parser Module"]:::core
        subgraph "Translations"
            direction TB
            AR["ar.yml"]:::core
            EN["en.yml"]:::core
            FR["fr.yml"]:::core
        end
        Localization["Localization Module"]:::core
        Output["Output Renderer"]:::cli
    end

    %% External Systems
    ExternalAPI["Ministry API\n(HTTP)"]:::external
    FileSystem["Filesystem"]:::external

    %% Packaging & Docs
    subgraph "Packaging Configuration" 
        direction TB
        Setup["setup.py"]:::ci
        Manifest["MANIFEST.in"]:::ci
        Requirements["requirements.txt"]:::ci
    end
    subgraph "CI/CD Pipeline"
        CI["GitHub Actions\n(pypi-publish.yml)"]:::ci
    end
    subgraph "Documentation & Licensing"
        README["README.md"]:::doc
        LICENSEF["LICENSE"]:::doc
    end

    %% Data Flow
    User --> CLI
    CLI --> Config
    Config --> FileSystem
    CLI --> Cache
    Cache --> FileSystem
    Cache -->|miss| HTTP
    HTTP --> ExternalAPI
    HTTP -->|response| Parser
    Parser --> Cache
    Parser --> Localization
    Localization --> AR
    Localization --> EN
    Localization --> FR
    Localization -->|formats| Output
    Output --> User

    %% Packaging & CI Flow
    PackageInit --> Setup
    Setup --> Manifest
    Setup --> Requirements
    CI --> Setup

    %% Documentation Link
    PackageInit --> README
    PackageInit --> LICENSEF

    %% Click Events
    click CLI "https://github.com/ismailbenhallam/moroccan-prayer-times/blob/main/moroccan_prayer_times/main.py"
    click PackageInit "https://github.com/ismailbenhallam/moroccan-prayer-times/blob/main/moroccan_prayer_times/__init__.py"
    click AR "https://github.com/ismailbenhallam/moroccan-prayer-times/blob/main/moroccan_prayer_times/translations/ar.yml"
    click EN "https://github.com/ismailbenhallam/moroccan-prayer-times/blob/main/moroccan_prayer_times/translations/en.yml"
    click FR "https://github.com/ismailbenhallam/moroccan-prayer-times/blob/main/moroccan_prayer_times/translations/fr.yml"
    click Setup "https://github.com/ismailbenhallam/moroccan-prayer-times/blob/main/setup.py"
    click Manifest "https://github.com/ismailbenhallam/moroccan-prayer-times/blob/main/MANIFEST.in"
    click Requirements "https://github.com/ismailbenhallam/moroccan-prayer-times/blob/main/requirements.txt"
    click CI "https://github.com/ismailbenhallam/moroccan-prayer-times/blob/main/.github/workflows/pypi-publish.yml"
    click README "https://github.com/ismailbenhallam/moroccan-prayer-times/blob/main/README.md"
    click LICENSEF "https://github.com/ismailbenhallam/moroccan-prayer-times/tree/main/LICENSE"

    %% Styles
    classDef cli fill:#d0e6f7,stroke:#0366d6,color:#0366d6;
    classDef core fill:#e6f7d0,stroke:#22863a,color:#22863a;
    classDef external fill:#f7e6d0,stroke:#d73a49,color:#d73a49;
    classDef ci fill:#f7d0e6,stroke:#6f42c1,color:#6f42c1;
    classDef doc fill:#edefed,stroke:#6a737d,color:#6a737d;
```
