# munal777/nprxchange-cli architecture

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

- Interactive diagram: https://gitdiagram.com/munal777/nprxchange-cli
- Repository: https://github.com/munal777/nprxchange-cli

## Overview

##### Project type and purpose
- nprxchange is a standalone, open-source CLI application written in Python.
- Its purpose is to convert Nepali Rupees (NPR) to other currencies using official NRB exchange rates, supporting both online fetches and offline cache.

##### Main architectural components
a. CLI Layer
- nprxchange/cli.py – parses command-line arguments (argparse) and/or launches interactive prompts (InquirerPy).
- Rich-based renderer for styled terminal output.
b. Core Conversion Logic
- nprxchange/converter.py – orchestrates the conversion calculation, takes NPR amount + target code, returns converted value.
c. API Layer
- nprxchange/api.py – HTTP client that fetches live rates from Nepal Rastra Bank API.
d. Storage (Cache) Layer
- nprxchange/storage.py – reads/writes a local cache (e.g., JSON or pickle file) for offline use.
e. External Dependencies & Services
- Python runtime, pip installation (setup.py)
- External libraries: requests (or httpx), Rich, InquirerPy
- Nepal Rastra Bank external API

##### Relationships and data flow
- User invokes `nprxchange` CLI → CLI Layer
→ If interactive: InquirerPy prompts → user selects amount & currency
→ CLI Layer calls Converter
→ Converter checks Storage:
– If cache is fresh/available → read from storage → return rate
– Otherwise → API Layer fetches rates → Storage updates cache → return rate
→ Converter applies exchange formula → returns result
→ CLI Layer passes result to Rich renderer → terminal output

##### Highlighted design principles & patterns
- Single Responsibility: each module (cli, converter, api, storage) has one job
- Layered architecture: CLI → Converter → (Storage ↔ API)
- Extensibility: clear module boundaries ease adding new features (e.g., new output formats)
- Offline-first strategy: transparent cache fallback

- [ ] Clear component names matching file names/modules
- [ ] Callouts for key technologies (Rich, InquirerPy, requests)
- [ ] Note of offline vs. online flow

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["cli.py\n(parses args, prompts)"]:::cli
        TERM["Terminal Output\n(Rich Renderer)"]:::cli
    end

    %% Core Logic
    subgraph "Core Logic"
        CONV["converter.py\n(calculates conversion)"]:::core
        INIT["__init__.py"]:::core
    end

    %% API Layer
    subgraph "API Layer"
        API["api.py\n(fetch live rates)"]:::external
    end

    %% Storage Layer
    subgraph "Storage Layer"
        STORE["storage.py\n(cache read/write)"]:::storage
    end

    %% External Service
    subgraph "External"
        NRB["NRB Exchange Rate API"]:::external
    end

    %% Other Components
    subgraph "Project Files"
        SETUP["setup.py"]:::docs
        README["README.md"]:::docs
    end

    %% Data Flow
    CLI -->|"invoke conversion"| CONV
    CONV -->|"check cache"| STORE
    STORE -->|"cache hit (rates)"| CONV
    CONV -->|"cache miss"| API
    API -->|"get rates"| NRB
    NRB -->|"response"| API
    API -->|"write cache"| STORE
    CONV -->|"result"| CLI
    CLI -->|"render output"| TERM

    %% Click Events
    click CLI "https://github.com/munal777/nprxchange-cli/blob/main/nprxchange/cli.py"
    click CONV "https://github.com/munal777/nprxchange-cli/blob/main/nprxchange/converter.py"
    click API "https://github.com/munal777/nprxchange-cli/blob/main/nprxchange/api.py"
    click STORE "https://github.com/munal777/nprxchange-cli/blob/main/nprxchange/storage.py"
    click INIT "https://github.com/munal777/nprxchange-cli/blob/main/nprxchange/__init__.py"
    click SETUP "https://github.com/munal777/nprxchange-cli/blob/main/setup.py"
    click README "https://github.com/munal777/nprxchange-cli/blob/main/README.md"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#0066cc,stroke-width:1px;
    classDef core fill:#d4edda,stroke:#28a745,stroke-width:1px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:1px;
    classDef storage fill:#ffe5b4,stroke:#cc8400,stroke-width:1px;
    classDef docs fill:#fff3cd,stroke:#856404,stroke-width:1px;
```
