How ttndevfullstack/gitlab-issues-analyzer works
1. What this service is
- This is a single Python application that watches GitLab issues, enriches them with GitLab data, runs AI analysis, and delivers a structured email report.
- It is intentionally lightweight: there is no database, and the app relies on environment configuration plus in-memory/runtime components.
2. Process topology
- The runtime appears to combine a server-rendered web dashboard with an automated issue-processing loop.
- main.py is the entry point that likely wires together the dashboard, monitoring, and report workflow in one process.
- The UI is backed by Jinja-style HTML templates in templates/, so the dashboard is part of the same application rather than a separate frontend.
3. Configuration boundary
- src/config.py centralizes environment-driven settings such as GitLab URL/token, AI provider choice, SMTP credentials, polling mode, poll interval, issue start time, and logging/timeout-related behavior.
- The README shows the app supports production, development, and testing modes, plus automation toggles like ENABLE_AUTOMATION and APP_MODE=poll.
- This configuration layer is the main boundary between deployment environment and application behavior.
4. Issue ingestion and monitoring
- src/monitor.py is the orchestration layer that detects work items to analyze.
- It likely supports polling and webhook-style automation, matching the README’s “real-time or periodic issue monitoring.”
- The monitor is responsible for selecting new issues based on scope/labels/start time and for limiting processing in testing or development modes.
5. GitLab data access
- src/gitlab_client.py is the external system adapter for GitLab.
- It fetches the core issue plus related context such as comments, related issues, and attachments before analysis starts.
- This module is the main boundary to the GitLab API and likely handles request formatting, pagination, and API error translation.
6. AI analysis subsystem
- src/analyzer.py sends the enriched issue payload to an AI provider, with support for OpenRouter and OpenAI.
- The README indicates reasoning mode and token limits are configurable, so the analyzer is the place where model selection and prompt/response handling matter.
- The analysis output is structured around the WWWH-TR framework: Why, What, Who, How, Test, Reflect.
7. Report generation and presentation
- src/reporter.py turns analysis results into the final structured report used for email and likely for dashboard issue detail views.
- The templates/issue_view.html, templates/issues_list.html, and templates/dashboard.html files indicate the app also presents issue status and analysis results in a human-readable web interface.
- This layer is the presentation boundary: it formats machine analysis into operator-facing summaries.
8. Notification delivery
- src/email_sender.py handles SMTP delivery of the analysis report.
- Email is the final outbound notification channel, and the README makes clear the report is sent to a configured recipient rather than stored in an application database.
- In the system diagram, this is the last step in the automated processing chain.
9. Supporting utilities
- src/image_url_converter.py suggests attachment/image references from GitLab are normalized before they are passed into the AI or report renderer.
- src/analysis_cache.py likely prevents duplicate work across polls or dashboard actions.
- src/exceptions.py provides domain-specific error types that keep GitLab, AI, and email failures distinct.
10. Primary data flow
- New or selected GitLab issue → monitor → GitLab API enrichment → AI analysis → WWWH-TR report generation → SMTP email delivery.
- The same analyzed issue data is also exposed through the dashboard for inspection or manual triggering.
- Because there is no database, the important state is either fetched live from GitLab or held transiently during a run.
11. Operational modes
- The app can run as an always-on poller, with intervals controlled by configuration.
- Development uses Docker Compose overrides and live reload behavior; production is containerized and optimized for scheduled/background execution.
- ISSUE_START_TIME and MAX_ISSUES_PER_POLL are key controls for preventing historical issue reprocessing.
12. Tests and validation
- The repository has strong test separation: unit, integration, and end-to-end tests under tests/.
- That structure reflects the architecture boundaries well: config, GitLab client, analyzer, email sender, monitor, and workflow orchestration are all testable as isolated components.
- pytest.ini, requirements-test.txt, and the dedicated integration helpers show the project is designed around validating each adapter independently.
13. Deployment and infrastructure
- Dockerfile, docker-compose.yml, and docker-compose.dev.yml are the main deployment artifacts.
- GitHub Actions workflows support CI and Docker publishing, so the app is intended to be shipped as a container image.
- There are no obvious external infrastructure dependencies beyond GitLab, an AI API provider, and SMTP.
14. Architecture summary for a diagram
- Draw the system as one containerized Python service with four main edges: inbound from GitLab, outbound to AI provider, outbound to SMTP, and inbound/outbound via the web dashboard.
- Inside the service, the central orchestrator is the monitor, which coordinates the GitLab client, analyzer, reporter, and email sender.
- The dashboard and templates are a parallel presentation path over the same underlying issue-analysis workflow.
Main entry points: monitor.py Monitor · analyzer.py Analyzer · dashboard.html Dashboard · main.py Main
Components 17
App Runtime
Single Python service that orchestrates monitoring, analysis, reporting, and delivery.
- Main · Process entrypoint that wires the service together.
main.py - Config · Environment-driven application settings and runtime modes.
src/config.py - Monitor · Selects issues to process and coordinates the workflow.
src/monitor.py - GitLab Client · Fetches issues and related context from GitLab.
src/gitlab_client.py - Analyzer · Builds prompts and calls the configured AI provider.
src/analyzer.py - Reporter · Converts analysis output into the structured report.
src/reporter.py - Email Sender · Sends the final report through SMTP.
src/email_sender.py - Analysis Cache · Prevents duplicate work across poll cycles and triggers.
src/analysis_cache.py - Image URLs · Normalizes attachment and image references before analysis.
src/image_url_converter.py - Exceptions · Shared domain errors for workflow, adapter, and delivery failures.
src/exceptions.py
Presentation
Server-rendered dashboard and issue views for operators.
- Dashboard · Server-rendered operator dashboard for issue status and details.
templates/dashboard.html - Issues List · Rendered list of monitored or analyzed issues.
templates/issues_list.html - Issue View · Rendered detail view for a single issue and its analysis.
templates/issue_view.html
External Systems
Third-party services the app integrates with.
- GitLab API · Source of issues, comments, related items, and attachments.
- AI Provider · OpenAI or OpenRouter model endpoint used for analysis.
- SMTP Server · Outbound email delivery destination.
- Operator · Person viewing the dashboard or receiving reports.
Connections 19
- Main → Config: loads · Bootstraps runtime behavior from environment settings.
- Main → Monitor: starts · Starts the monitoring and processing loop.
- Main → Dashboard: serves · Exposes the web dashboard in the same process.
- Monitor → Config: reads · Uses mode, polling, and scope controls.
- Monitor → Analysis Cache: checks · Avoids reprocessing already handled issues.
- Monitor → GitLab Client: fetches · Retrieves issue data and surrounding context.
- GitLab Client → GitLab API: calls · Performs GitLab API requests.
- Monitor → Image URLs: normalizes · Prepares attachment and image references.
- Monitor → Analyzer: dispatches · Hands enriched issue payloads to AI analysis.
- Analyzer → Config: reads · Uses provider, model, and token settings.
- Analyzer → AI Provider: calls · Sends prompts and receives structured analysis.
- Analyzer → Reporter: produces · Transforms analysis into report-ready structure.
- Reporter → Email Sender: formats for · Prepares the report for outbound delivery.
- Email Sender → SMTP Server: sends · Delivers the report by email.
- Monitor → Exceptions: handles · Surfaces workflow and adapter failures.
- Dashboard → Issues List: shows · Renders the issue overview page.
- Dashboard → Issue View: shows · Renders detailed issue analysis views.
- Operator → Dashboard: uses · Views status and issue analysis in the browser.
- Operator → SMTP Server: receives · Gets the final email report.