# ivishalgandhi/jirax architecture

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

- Interactive diagram: https://gitdiagram.com/ivishalgandhi/jirax
- Repository: https://github.com/ivishalgandhi/jirax

## Overview

##### Project Type and Purpose
- Type: Open-source command-line utility (no GUI or web frontend).
- Purpose: Connect to a Jira server over REST, retrieve issues (by project key or JQL), transform them to tabular form, optionally preview, and export to CSV.

a. User / CLI Client
– Represents the end user invoking commands in a terminal (e.g., `jirax extract`, `jirax configure`).
b. Configuration Loader
– Reads TOML files in precedence order (CLI‐specified, local `./config.toml`, global `~/.jirax/config.toml`).
c. Authentication Manager
– Uses config values (auth_type, token, email/login) to prepare HTTP headers.
d. Jira API Client
– HTTP layer (requests or similar) that issues REST calls (project list, JQL search).
e. Data Extraction & Transformation
– `jirax.py` core: parses JSON, extracts required fields, adds metadata (Extract_Date), identifies Epics vs. Stories, applies max_results.
f. Preview/Console Output
– Renders a table of first N rows if preview enabled (`rich` or plain).
g. CSV Exporter
– Writes full result set to disk (`.csv`) at configured output path.
h. Command Modules
– `extract`, `configure`, `list-projects` commands implemented via Click (in `__main__.py`, `list_projects.py`).
i. File System & Logging
– Reads/writes config, writes exports, writes logs.
j. Tests (optional)
– Simulate commands; mock HTTP responses; verify CSV and error handling.

##### Relationships & Data Flows
1. CLI invocation → Configuration Loader
2. Loaded config → Authentication Manager
3. Auth Manager → Jira API Client (HTTP call) → Jira REST API (external cloud or server)
4. API response → Data Extraction & Transformation
5a. Transformation → Previewer → CLI stdout
5b. Transformation → CSV Exporter → Disk
6. Commands return exit codes to CLI / user

##### Architectural Patterns & Principles
- Modular separation: IO (HTTP, FS), core logic (parsing, transformation), CLI interface.
- Command pattern: each CLI subcommand encapsulated in its own module.
- Configuration precedence / override strategy.
- Single‐process, synchronous flow.

##### Technologies & Frameworks
- Python 3.8+
- Click (for CLI commands)
- TOML parser (e.g., `tomli` or `toml`)
- HTTP library (e.g., `requests`)
- CSV (built-in `csv` module)
- pytest (in `tests/`)
- Rich console output (optional)

- Clear labels: component names, file paths or module names (e.g., `jirax/jirax.py`).
– Config retrieval (CLI → Config Loader)
– Auth header injection (Loader → API Client)
– HTTP request/response (API Client ↔ Jira).
– Data flow into Preview and Exporter.
- Notes/callouts for:
– Config precedence logic.
– Supported auth types (basic vs. bearer).
– Default extraction settings (max_results, default_project).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and CLI
    User["User / CLI Client"]:::frontend
    Commands["Command Modules"]:::frontend
    ListProjects["list-projects Module"]:::frontend

    %% Configuration and I/O
    ConfigLoader["Configuration Loader"]:::io
    AuthManager["Authentication Manager"]:::core
    APIClient["Jira API Client"]:::io
    Filesystem["File System & Logging"]:::io

    %% Core Logic
    DataExtract["Data Extraction & Transformation"]:::core

    %% Output
    Previewer["Preview / Console Output"]:::frontend
    CSVExporter["CSV Exporter"]:::io

    %% External
    JiraREST["Jira REST API"]:::external

    %% Connections
    User -->|"invoke CLI"| Commands
    Commands -->|"load config"| ConfigLoader
    ConfigLoader -->|"config values"| AuthManager
    AuthManager -->|"auth headers"| APIClient
    APIClient -->|"JQL query"| JiraREST
    JiraREST -->|"JSON issues"| APIClient
    APIClient -->|"response JSON"| DataExtract
    DataExtract -->|"subset for preview"| Previewer
    Previewer -->|"table stdout"| User
    DataExtract -->|"full dataset"| CSVExporter
    CSVExporter -->|"write CSV"| Filesystem
    ConfigLoader -->|"read/write config/logs"| Filesystem

    %% Click Events
    click User "https://github.com/ivishalgandhi/jirax/blob/main/jirax/__main__.py"
    click Commands "https://github.com/ivishalgandhi/jirax/blob/main/jirax/__main__.py"
    click ListProjects "https://github.com/ivishalgandhi/jirax/blob/main/jirax/list_projects.py"
    click ConfigLoader "https://github.com/ivishalgandhi/jirax/blob/main/jirax/jirax.py"
    click AuthManager "https://github.com/ivishalgandhi/jirax/blob/main/jirax/jirax.py"
    click APIClient "https://github.com/ivishalgandhi/jirax/blob/main/jirax/jirax.py"
    click DataExtract "https://github.com/ivishalgandhi/jirax/blob/main/jirax/jirax.py"
    click Previewer "https://github.com/ivishalgandhi/jirax/blob/main/jirax/jirax.py"
    click CSVExporter "https://github.com/ivishalgandhi/jirax/blob/main/jirax/jirax.py"
    click Filesystem "https://github.com/ivishalgandhi/jirax/blob/main/jirax/jirax.py"

    %% Styles
    classDef frontend fill:#85C1E9,stroke:#21618C,color:#000;
    classDef core fill:#A9DFBF,stroke:#196F3D,color:#000;
    classDef io fill:#F5B041,stroke:#B9770E,color:#000;
    classDef external fill:#D5D8DC,stroke:#7F8C8D,color:#000;
```
