# ttndevfullstack/gitlab-issues-analyzer architecture

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

- Interactive diagram: https://gitdiagram.com/ttndevfullstack/gitlab-issues-analyzer
- Repository: https://github.com/ttndevfullstack/gitlab-issues-analyzer

## Overview

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: [`src/monitor.py`](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/monitor.py) (Monitor), [`src/analyzer.py`](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/analyzer.py) (Analyzer), [`templates/dashboard.html`](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/templates/dashboard.html) (Dashboard), [`main.py`](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/main.py) (Main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App Runtime"]
  node_main["Main<br/>entrypoint<br/>[main.py]"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_monitor{{"Monitor<br/>orchestrator<br/>[monitor.py]"}}
  node_gitlab_client["GitLab Client<br/>adapter<br/>[gitlab_client.py]"]
  node_analyzer["Analyzer<br/>ai pipeline<br/>[analyzer.py]"]
  node_reporter["Reporter<br/>formatter<br/>[reporter.py]"]
  node_email_sender["Email Sender<br/>smtp adapter<br/>[email_sender.py]"]
  node_analysis_cache(("Analysis Cache<br/>[analysis_cache.py]"))
  node_image_url_converter["Image URLs<br/>normalizer"]
  node_exceptions["Exceptions<br/>error model<br/>[exceptions.py]"]
end

subgraph group_presentation["Presentation"]
  node_dashboard["Dashboard<br/>web ui<br/>[dashboard.html]"]
  node_issues_list["Issues List<br/>web view<br/>[issues_list.html]"]
  node_issue_view["Issue View<br/>web view<br/>[issue_view.html]"]
end

subgraph group_external["External Systems"]
  node_gitlab_api[("GitLab API<br/>external api")]
  node_ai_provider[("AI Provider<br/>external api")]
  node_smtp_server[("SMTP Server<br/>external service")]
  node_operator(("Operator<br/>user"))
end

node_main -->|"loads"| node_config
node_main -->|"starts"| node_monitor
node_main -->|"serves"| node_dashboard
node_monitor -->|"reads"| node_config
node_monitor -->|"checks"| node_analysis_cache
node_monitor -->|"fetches"| node_gitlab_client
node_gitlab_client -->|"calls"| node_gitlab_api
node_monitor -->|"normalizes"| node_image_url_converter
node_monitor -->|"dispatches"| node_analyzer
node_analyzer -->|"reads"| node_config
node_analyzer -->|"calls"| node_ai_provider
node_analyzer -->|"produces"| node_reporter
node_reporter -->|"formats for"| node_email_sender
node_email_sender -->|"sends"| node_smtp_server
node_monitor -.->|"handles"| node_exceptions
node_dashboard -->|"shows"| node_issues_list
node_dashboard -->|"shows"| node_issue_view
node_operator -->|"uses"| node_dashboard
node_operator -->|"receives"| node_smtp_server

click node_main "https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/main.py"
click node_config "https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/config.py"
click node_monitor "https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/monitor.py"
click node_gitlab_client "https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/gitlab_client.py"
click node_analyzer "https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/analyzer.py"
click node_reporter "https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/reporter.py"
click node_email_sender "https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/email_sender.py"
click node_analysis_cache "https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/analysis_cache.py"
click node_image_url_converter "https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/image_url_converter.py"
click node_exceptions "https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/exceptions.py"
click node_dashboard "https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/templates/dashboard.html"
click node_issues_list "https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/templates/issues_list.html"
click node_issue_view "https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/templates/issue_view.html"

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_main,node_config,node_monitor,node_gitlab_client,node_analyzer,node_reporter,node_email_sender,node_analysis_cache,node_image_url_converter,node_exceptions toneBlue
class node_dashboard,node_issues_list,node_issue_view toneAmber
class node_gitlab_api,node_ai_provider,node_smtp_server,node_operator toneMint
```

## Components

### App Runtime

Single Python service that orchestrates monitoring, analysis, reporting, and delivery.

- [Main](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/main.py): entrypoint · Process entrypoint that wires the service together. · `main.py`
- [Config](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/config.py): settings · Environment-driven application settings and runtime modes. · `src/config.py`
- [Monitor](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/monitor.py): orchestrator · Selects issues to process and coordinates the workflow. · `src/monitor.py`
- [GitLab Client](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/gitlab_client.py): adapter · Fetches issues and related context from GitLab. · `src/gitlab_client.py`
- [Analyzer](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/analyzer.py): ai pipeline · Builds prompts and calls the configured AI provider. · `src/analyzer.py`
- [Reporter](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/reporter.py): formatter · Converts analysis output into the structured report. · `src/reporter.py`
- [Email Sender](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/email_sender.py): smtp adapter · Sends the final report through SMTP. · `src/email_sender.py`
- [Analysis Cache](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/analysis_cache.py): cache · Prevents duplicate work across poll cycles and triggers. · `src/analysis_cache.py`
- [Image URLs](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/image_url_converter.py): normalizer · Normalizes attachment and image references before analysis. · `src/image_url_converter.py`
- [Exceptions](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/src/exceptions.py): error model · Shared domain errors for workflow, adapter, and delivery failures. · `src/exceptions.py`

### Presentation

Server-rendered dashboard and issue views for operators.

- [Dashboard](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/templates/dashboard.html): web ui · Server-rendered operator dashboard for issue status and details. · `templates/dashboard.html`
- [Issues List](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/templates/issues_list.html): web view · Rendered list of monitored or analyzed issues. · `templates/issues_list.html`
- [Issue View](https://github.com/ttndevfullstack/gitlab-issues-analyzer/blob/main/templates/issue_view.html): web 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**: external api · Source of issues, comments, related items, and attachments.
- **AI Provider**: external api · OpenAI or OpenRouter model endpoint used for analysis.
- **SMTP Server**: external service · Outbound email delivery destination.
- **Operator**: user · Person viewing the dashboard or receiving reports.

## Connections

- 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.
