# jyotirmoy0989/jira_delivery_tracker architecture

> Architecture diagram of the GitHub repository jyotirmoy0989/jira_delivery_tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jyotirmoy0989/jira_delivery_tracker
- Repository: https://github.com/jyotirmoy0989/jira_delivery_tracker

## Overview

#### Purpose and entry point
This is a Python migration/automation utility that converts delivery-tracker spreadsheet data into Jira-compatible work items. The primary executable is `main.py`; its expected source and generated artifacts are `data/input/Delivery_Tracker.xlsx`, `data/output/jira_epics.csv`, and `data/output/jira_tasks.csv`.

#### Workflow orchestration
`main.py` likely composes the Excel ingestion, transformation, and Jira-output stages. Workflow behavior and shared operational values are centralized under `config/workflow.py`, `config/settings.py`, and `config/constants.py`, creating a boundary between pipeline logic and environment/project-specific rules.

#### Excel ingestion and quality gate
The Excel subsystem owns conversion from workbook structure into internal records:
- `src/excel/reader.py` reads the tracker workbook.
- `src/excel/validator.py` validates expected source data before downstream Jira generation.
- `src/excel/transformer.py` normalizes or reshapes validated rows into Jira-oriented entities.

The key boundary is between user-maintained Excel input and structured migration records; invalid or incomplete tracker data should be handled before Jira artifacts or API calls are produced.

#### Field mapping and domain translation
`config/field_mapping.py` defines the critical correspondence between delivery-tracker fields and Jira fields. Together with `config/workflow.py`, it likely controls how source work is classified into epics versus tasks and how parent/child relationships, labels, and other Jira attributes are populated. This mapping layer is the main contract that must evolve when either the spreadsheet schema or Jira project conventions change.

#### Jira output and service boundary
The Jira package supports both file-based and API-based integration:
- `src/jira/csv_generator.py` produces importable CSVs, represented by `data/output/jira_epics.csv` and `data/output/jira_tasks.csv`.
- `src/jira/api.py` and `src/jira/jira_service.py` encapsulate direct Jira communication.
- `src/jira/create_epic.py` specializes creation of epic-level Jira work items.
- `src/jira/migrate_labels.py` handles label migration/update behavior.

CSV generation is an offline/import boundary; the API/service modules are the external-service boundary and should isolate Jira authentication, request behavior, and response/error handling from Excel transformation logic.

#### Runtime and observability
The repository is a Python application, with dependencies declared in `requirements.txt`. Logging is centralized in `src/logger/logger.py` and should provide pipeline-stage visibility across workbook processing, CSV creation, and Jira operations. Jira is the material external service; the local filesystem hosts both the workbook input and generated migration outputs.

Main entry points: [`main.py`](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/main.py) (Migration CLI), [`src/excel/transformer.py`](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/excel/transformer.py) (Jira transformer), [`src/jira/jira_service.py`](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/jira/jira_service.py) (Jira service), [`src/jira/csv_generator.py`](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/jira/csv_generator.py) (CSV generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_config["Configuration"]
  node_workflow_config["Workflow rules<br/>workflow config<br/>[workflow.py]"]
  node_settings["Settings<br/>[settings.py]"]
  node_constants["Constants<br/>[constants.py]"]
  node_field_mapping["Field mapping<br/>mapping config<br/>[field_mapping.py]"]
end

subgraph group_excel["Excel pipeline"]
  node_excel_reader["Workbook reader<br/>Excel ingestion<br/>[reader.py]"]
  node_excel_validator["Source validator<br/>quality gate<br/>[validator.py]"]
  node_excel_transformer["Jira transformer<br/>record transformation<br/>[transformer.py]"]
end

subgraph group_jira["Jira integration"]
  node_csv_generator["CSV generator<br/>Jira CSV export<br/>[csv_generator.py]"]
  node_epics_csv["Epic import CSV<br/>generated CSV<br/>[jira_epics.csv]"]
  node_tasks_csv["Task import CSV<br/>generated CSV<br/>[jira_tasks.csv]"]
  node_jira_service["Jira service<br/>service boundary<br/>[jira_service.py]"]
  node_jira_api["Jira API client<br/>external API client<br/>[api.py]"]
  node_create_epic["Epic creator<br/>Jira operation<br/>[create_epic.py]"]
  node_migrate_labels["Label migration<br/>Jira operation<br/>[migrate_labels.py]"]
end

node_main["Migration CLI<br/>Python entry point<br/>[main.py]"]
node_input_workbook["Delivery tracker<br/>Excel workbook"]
node_jira{{"Jira<br/>external service"}}
node_logger["Pipeline logger<br/>observability<br/>[logger.py]"]
node_requirements["Python dependencies<br/>dependency manifest<br/>[requirements.txt]"]

node_main -->|"uses"| node_workflow_config
node_main -->|"uses"| node_settings
node_main -->|"uses"| node_constants
node_main -->|"starts ingestion"| node_excel_reader
node_input_workbook -->|"read by"| node_excel_reader
node_excel_reader -->|"source records"| node_excel_validator
node_excel_validator -->|"validated rows"| node_excel_transformer
node_field_mapping -->|"maps fields"| node_excel_transformer
node_workflow_config -->|"classifies work"| node_excel_transformer
node_excel_transformer -->|"Jira entities"| node_csv_generator
node_csv_generator -->|"writes"| node_epics_csv
node_csv_generator -->|"writes"| node_tasks_csv
node_excel_transformer -.->|"work items"| node_jira_service
node_jira_service -->|"uses"| node_jira_api
node_jira_service -->|"creates epics"| node_create_epic
node_jira_service -->|"migrates labels"| node_migrate_labels
node_jira_api -->|"API requests"| node_jira
node_create_epic -->|"creates"| node_jira
node_migrate_labels -->|"updates"| node_jira
node_main -.->|"logs through"| node_logger
node_requirements -.->|"runtime dependencies"| node_main

click node_main "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/main.py"
click node_input_workbook "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/data/input/Delivery_Tracker.xlsx"
click node_workflow_config "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/config/workflow.py"
click node_settings "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/config/settings.py"
click node_constants "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/config/constants.py"
click node_field_mapping "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/config/field_mapping.py"
click node_excel_reader "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/excel/reader.py"
click node_excel_validator "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/excel/validator.py"
click node_excel_transformer "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/excel/transformer.py"
click node_csv_generator "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/jira/csv_generator.py"
click node_epics_csv "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/data/output/jira_epics.csv"
click node_tasks_csv "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/data/output/jira_tasks.csv"
click node_jira_service "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/jira/jira_service.py"
click node_jira_api "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/jira/api.py"
click node_create_epic "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/jira/create_epic.py"
click node_migrate_labels "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/jira/migrate_labels.py"
click node_logger "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/logger/logger.py"
click node_requirements "https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/requirements.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_workflow_config,node_settings,node_constants,node_field_mapping toneBlue
class node_excel_reader,node_excel_validator,node_excel_transformer toneAmber
class node_csv_generator,node_epics_csv,node_tasks_csv,node_jira_service,node_jira_api,node_create_epic,node_migrate_labels toneMint
class node_main,node_input_workbook,node_jira,node_logger,node_requirements toneNeutral
```

## Components

### Configuration

Pipeline rules and source-to-Jira contracts.

- [Workflow rules](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/config/workflow.py): workflow config · Controls pipeline behavior and work classification. · `config/workflow.py`
- [Settings](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/config/settings.py): settings config · Holds environment or project-specific values. · `config/settings.py`
- [Constants](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/config/constants.py): constants config · `config/constants.py`
- [Field mapping](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/config/field_mapping.py): mapping config · Defines delivery-tracker to Jira field correspondence. · `config/field_mapping.py`

### Excel pipeline

Workbook ingestion, validation, and normalization.

- [Workbook reader](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/excel/reader.py): Excel ingestion · Reads workbook structure into internal records. · `src/excel/reader.py`
- [Source validator](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/excel/validator.py): quality gate · Rejects invalid or incomplete tracker data before output. · `src/excel/validator.py`
- [Jira transformer](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/excel/transformer.py): record transformation · Normalizes validated rows into Jira-oriented entities. · `src/excel/transformer.py`

### Jira integration

Offline import generation and direct Jira operations.

- [CSV generator](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/jira/csv_generator.py): Jira CSV export · Creates importable epic and task files. · `src/jira/csv_generator.py`
- [Epic import CSV](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/data/output/jira_epics.csv): generated CSV · `data/output/jira_epics.csv`
- [Task import CSV](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/data/output/jira_tasks.csv): generated CSV · `data/output/jira_tasks.csv`
- [Jira service](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/jira/jira_service.py): service boundary · Isolates Jira request, response, and error behavior. · `src/jira/jira_service.py`
- [Jira API client](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/jira/api.py): external API client · Encapsulates direct Jira communication. · `src/jira/api.py`
- [Epic creator](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/jira/create_epic.py): Jira operation · Creates epic-level Jira work items. · `src/jira/create_epic.py`
- [Label migration](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/jira/migrate_labels.py): Jira operation · Migrates or updates Jira labels. · `src/jira/migrate_labels.py`

### Other components

- [Migration CLI](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/main.py): Python entry point · Orchestrates the delivery-tracker migration workflow. · `main.py`
- [Delivery tracker](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/data/input/Delivery_Tracker.xlsx): Excel workbook · User-maintained migration source. · `data/input/Delivery_Tracker.xlsx`
- **Jira**: external service · Target work-management service.
- [Pipeline logger](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/src/logger/logger.py): observability · Provides visibility across migration stages. · `src/logger/logger.py`
- [Python dependencies](https://github.com/jyotirmoy0989/jira_delivery_tracker/blob/main/requirements.txt): dependency manifest · `requirements.txt`

## Connections

- Migration CLI → Workflow rules: uses
- Migration CLI → Settings: uses
- Migration CLI → Constants: uses
- Migration CLI → Workbook reader: starts ingestion
- Delivery tracker → Workbook reader: read by
- Workbook reader → Source validator: source records
- Source validator → Jira transformer: validated rows
- Field mapping → Jira transformer: maps fields
- Workflow rules → Jira transformer: classifies work
- Jira transformer → CSV generator: Jira entities
- CSV generator → Epic import CSV: writes
- CSV generator → Task import CSV: writes
- Jira transformer → Jira service: work items
- Jira service → Jira API client: uses
- Jira service → Epic creator: creates epics
- Jira service → Label migration: migrates labels
- Jira API client → Jira: API requests
- Epic creator → Jira: creates
- Label migration → Jira: updates
- Migration CLI → Pipeline logger: logs through
- Python dependencies → Migration CLI: runtime dependencies