# fuzzylabs/troll architecture

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

- Interactive diagram: https://gitdiagram.com/fuzzylabs/troll
- Repository: https://github.com/fuzzylabs/troll

## Overview

##### Project type and purpose
- TROLL is a command-line interface (CLI) tool written in Python.
- Its purpose is to fetch Jira tickets, gather context from GitHub, invoke an LLM (e.g., Gemini) to enrich ticket content, display a preview, and update Jira with improved text.
- It is an open-source developer productivity tool integrating three external systems (Jira, GitHub, Gemini).

##### File structure
- Top-level files:
- pyproject.toml: build and dependency management
- README.md / TEMPLATE.md / example.env: documentation and configuration template
- .gitignore, LICENSE: standard repo files
- Python package “troll/”:
- __main__.py: CLI entrypoint (console_scripts “troll”)
- config.py: environment-variable and .env loader
- clients/: Jira, GitHub, and LLM client abstractions
- utils/: core helpers (ticket data models, exception handling)
- No separate frontend or database – all state is transient or passed through API calls.

##### README for architectural cues
- Steps: setup → interactive or direct CLI command → fetch tickets → gather context → AI enhancement → preview → update.
- External dependencies: Jira REST API, GitHub REST API, Gemini API.
- Customization: TEMPLATE.md drives output formatting.

##### Main components
a. CLI Layer
- User’s terminal invokes the “troll” command
- Entrypoint in troll/__main__.py
b. Configuration Manager
- troll/config.py reads .env variables into runtime settings
c. Core Orchestrator
- Central workflow bringing together clients and utils
- Handles interactive menus, JQL search, ID parsing
d. Client Abstractions
- JiraClient (clients/jira.py): fetch/update tickets
- GitHubClient (clients/github.py): scan commits, issues, code tree
- LLMClient (clients/llm.py): send prompt to Gemini, receive enhanced text
e. Utility Modules
- tickets.py: data models for ticket content and transformation
- exceptions.py: standardized error handling
f. Template Engine
- TEMPLATE.md is loaded and rendered with context to format AI prompts and output
g. External Systems
- Jira REST API
- GitHub REST API
- Gemini (LLM) API

##### Relationships and data flow
1) User → CLI Layer: invokes “troll”
2) CLI Layer → Configuration Manager: load JIRA_URL, tokens, repo settings
3) CLI Layer → Core Orchestrator: pass command arguments or interactive flags
4) Core Orchestrator → JiraClient: list or get ticket details
5) Core Orchestrator → GitHubClient: collect context (commits, issues, code)
6) Core Orchestrator → Template Engine + context → LLMClient: generate improved title/description
7) LLMClient → Core Orchestrator: return enhanced text
8) Core Orchestrator → Preview UI (CLI) → User
9) On confirmation: Core Orchestrator → JiraClient: update ticket

##### Architectural patterns and design principles
- Modular separation of concerns:
- Entrypoint vs. config vs. orchestrator vs. clients vs. utils
- Client abstraction pattern: isolates external API calls behind interfaces
- Template-driven prompting: decouples formatting from business logic
- Single responsibility: each module has a well-defined role
- Transient state: no persistent storage; all data flows through memory and API calls

##### Detail
- Error-handling paths (exceptions module) if desired
- Call out the TEMPLATE.md as a plug-in point for custom ticket formatting
- Components listed in the file tree to ensure nothing is omitted

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Invocation
    User["User Terminal"]:::external
    User -->|"invoke troll"| CLI

    %% Internal Components
    CLI["CLI Layer"]:::internal
    Config["Configuration Manager"]:::internal
    Orchestrator["Core Orchestrator"]:::internal
    Metadata["Project Metadata\n(pyproject.toml)"]:::internal
    Readme["Documentation\n(README.md)"]:::internal
    Env["Config Template\n(example.env)"]:::internal

    subgraph "Clients"
        JiraClient["JiraClient"]:::internal
        GitHubClient["GitHubClient"]:::internal
        LLMClient["LLMClient"]:::internal
    end

    subgraph "Utilities"
        Tickets["Tickets Data Models"]:::internal
        Exceptions["Exception Handling"]:::internal
    end

    TemplateEngine["Template Engine\n(TEMPLATE.md)"]:::internal

    subgraph "External Services"
        JiraAPI["Jira REST API"]:::external
        GitHubAPI["GitHub REST API"]:::external
        LLMAPI["Gemini LLM API"]:::external
    end

    %% Data Flow
    CLI -->|"load config"| Config
    CLI -->|"pass args"| Orchestrator
    CLI -->|"load project metadata"| Metadata
    CLI -->|"load docs"| Readme
    CLI -->|"load env template"| Env

    Orchestrator -->|"fetchTicket()"| JiraClient
    Orchestrator -->|"gatherContext()"| GitHubClient
    Orchestrator -->|"buildPrompt()"| TemplateEngine
    Orchestrator -->|"generatePrompt()"| LLMClient
    Orchestrator -->|"use models/exceptions"| Tickets
    Orchestrator -->|"use models/exceptions"| Exceptions

    JiraClient -->|"HTTP requests"| JiraAPI
    GitHubClient -->|"HTTP requests"| GitHubAPI
    LLMClient -->|"sendPrompt()"| LLMAPI
    LLMAPI -->|"return text"| LLMClient
    LLMClient -->|"return enhancedText"| Orchestrator

    Orchestrator -->|"preview()"| CLI
    CLI -->|"userConfirm()"| Orchestrator
    Orchestrator -->|"updateTicket()"| JiraClient

    %% Click Events
    click CLI "https://github.com/fuzzylabs/troll/blob/main/troll/__main__.py"
    click Config "https://github.com/fuzzylabs/troll/blob/main/troll/config.py"
    click Orchestrator "https://github.com/fuzzylabs/troll/blob/main/troll/__main__.py"
    click JiraClient "https://github.com/fuzzylabs/troll/blob/main/troll/clients/jira.py"
    click GitHubClient "https://github.com/fuzzylabs/troll/blob/main/troll/clients/github.py"
    click LLMClient "https://github.com/fuzzylabs/troll/blob/main/troll/clients/llm.py"
    click Tickets "https://github.com/fuzzylabs/troll/blob/main/troll/utils/tickets.py"
    click Exceptions "https://github.com/fuzzylabs/troll/blob/main/troll/utils/exceptions.py"
    click TemplateEngine "https://github.com/fuzzylabs/troll/blob/main/TEMPLATE.md"
    click Metadata "https://github.com/fuzzylabs/troll/blob/main/pyproject.toml"
    click Readme "https://github.com/fuzzylabs/troll/blob/main/README.md"
    click Env "https://github.com/fuzzylabs/troll/blob/main/example.env"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#1B4F72,color:#1B2631;
    classDef external fill:#D5F5E3,stroke:#145A32,color:#0B5345;
```
