# Architecture

devx is a reusable Python package providing development and CI/CD tools for oblachno-oss projects.

## Package Structure

```
src/devx/
├── __init__.py          # Version (single source of truth)
├── cli.py               # Click-based CLI entry point (devx command)
├── config.py            # Configuration system (DEVX_ env vars)
├── api_clients.py       # GiteaClient, VikunjaClient — HTTP API wrappers
├── gitea_cli.py         # TeaCLI — wrapper around tea CLI with JSON parsing
├── i18n.py              # Translation system (gettext-based, translations.json)
├── exceptions.py        # Custom exception types (DevxError, APIError)
├── translations.json    # Translation strings (en, bg, de, ru, zh)
├── ci/                  # CI/CD automation modules
├── tools/               # Developer tooling modules
└── molecule/            # Optional molecule testing helpers
```

## Core Modules

### cli.py

Click-based CLI entry point. Provides three command groups: `devx ci`, `devx tools`, `devx molecule`. Each subcommand delegates to the corresponding module via `_run_module()`.

### i18n.py

Simple i18n system using a JSON translations file. Supports en, bg, de, ru, zh. Projects can extend translations by setting `DEVX_TRANSLATIONS_PATH` to a custom JSON file.

### exceptions.py

Custom exception hierarchy: `DevxError` (base), `APIError` (HTTP errors with status code and message).

### api_clients.py

HTTP API clients with connection pooling and retry logic:
- `GiteaClient` — Gitea REST API (branch protection, labels, issues, PRs, releases, reviews)
- `VikunjaClient` — Vikunja REST API (tasks, projects, comments)

Both clients retry on transient errors (429, 5xx, connection errors) with exponential backoff.

### config.py

Configuration constants with env-var overrides (`DEVX_` prefix). Includes API URLs, timeouts, retry settings, task prefix regex, and conventional commit regex.

### gitea_cli.py

Python wrapper around the `tea` Gitea CLI tool. Parses JSON output for structured data. Used by CI scripts for Gitea API operations (issues, labels, PRs, releases, reviews).