How fuzzylabs/troll works
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