# istin/dmtools architecture

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

- Interactive diagram: https://gitdiagram.com/istin/dmtools
- Repository: https://github.com/istin/dmtools

## Overview

##### Project Type and Purpose
- DMTools is a Java-based, full-stack CLI/library tool (monolithic JAR) offering “Delivery Management” features.
- It’s invoked via a job trigger (UrlEncodedJobTrigger) and integrates with external systems (Jira, GitHub, GitLab, Bitbucket, Rally, Confluence, Figma, OpenAI, Firebase, AppCenter) to collect, analyze, enrich, and report data.
- It also includes a simple Chrome Extension for user interaction (popup and settings).

##### File Structure
- Top-level build: Gradle wrapper, build.gradle, settings.gradle, GitHub workflows, gradle-publish.
- chrome_extension/: simple UI layer.
- src/main/java/com/github/istin/dmtools/: core packages by domain:
- job – JobRunner, UrlEncodedJobTrigger
- di – dependency-injection modules for AI, Atlassian, context, agents, search, etc.
- ai – orchestrator, agents, AI client adapters (OpenAI, CurlAI).
- atlassian, github, gitlab, broadcom.rally, bitbucket – REST client adapters/models.
- common – shared models, utils, networking.
- src/test & src/integrationTest: comprehensive unit & integration tests.

##### README
- Describes: CLI invocation, environment-variable-driven configuration for each external service.
- Mentions: API description for job params, JAR build, configuration for Jira, Rally, Bitbucket, GitHub, GitLab, Confluence, OpenAI, CurlAI, Figma, Firebase, AppCenter.

a. Main Components
- CLI Launcher: UrlEncodedJobTrigger → JobRunner
- DI Container: wires selected modules & agents
- Job service layer: AbstractJob & concrete Job implementations
- Context Orchestrator: aggregates inputs (files, tickets, code)
- AI Layer: AIProvider, AI clients (OpenAI/CurlAI), agents
- Adapters for External Systems: Jira, GitHub, GitLab, Bitbucket, Rally, Confluence, Figma, Firebase, AppCenter
- Reporting & Output: Freemarker template engine → HTML, PDF, Excel, Markdown
- Optional UI: Chrome Extension (popup/settings)
b. Relationships & Data Flow
1. User invokes CLI with base64 JobParams → CLI Launcher
2. JobRunner parses params & selects Job implementation
3. DI Container injects required clients & orchestrators
4. Job uses adapters to fetch data from external systems
5. ContextOrchestrator + ChunkPreparation prepare inputs for AI
6. AI Layer (through AIProvider) calls external AI API
7. Agents process AI responses, merge content, generate artifacts
8. Reporting modules apply Freemarker templates → deliver output files or update Confluence/Jira
9. Chrome Extension can display results, allow settings modification
c. Architectural Patterns & Principles
- Modular package organization by domain
- Adapter pattern for each external REST API
- Dependency Injection (via custom DI modules)
- Template Method for Jobs
- Strategy/Agent pattern for AI tasks
- Template Engine (Freemarker) for outputs
- Separation of concerns: data retrieval, processing, AI, templating
d. Key Technologies & Frameworks
- Java 11+; Gradle (shadowJar plugin)
- Freemarker for templating
- HTTP clients (RestClient, AtlassianRestClient)
- Base64-encoded JobParam API
- Chrome Extension (HTML/JS manifest v2/3)

##### Essential Elements
- Labels: component name, package/module
- Green: Internal services (Jobs, Agents)
- Blue: External integrations (Jira, GitHub, …)
- Yellow: AI subsystem
- Gray: Output (Freemarker, templates)
- Orange: CLI & UI (Chrome Extension)
- Notes on triggers (base64 JobParams) and DI assembly.

##### Final Advice
- Major domain modules you see under src/main/java/com/github/istin/dmtools.
- Platform as a single monolith broken into logical layers, not microservices.
- Don’t over-fragment—group by layer/domain.
- Be detailed but clear: the goal is to reflect how data moves from CLI → adapters → AI → agents → templates → outputs.
- Review the README’s list of supported systems to ensure each adapter is shown.
- Iterate with the team: they may want to show sample Jobs (e.g., “DevProductivityReport” job) as examples.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        DMTools["DMTools"]:::cli
        UrlEncodedJobTrigger["UrlEncodedJobTrigger"]:::cli
        JobRunner["JobRunner"]:::cli
    end

    %% Dependency Injection
    subgraph "Dependency Injection Container"
        direction TB
        DIContainer["DI Container"]:::internal
    end

    %% Job Service Layer
    subgraph "Job Service Layer"
        direction TB
        AbstractJob["AbstractJob"]:::internal
        BaseJobParams["BaseJobParams"]:::internal
        JobInterface["Job"]:::internal
        JobParams["JobParams"]:::internal
    end

    %% Context Orchestrator
    subgraph "Context Orchestrator"
        direction TB
        ContextOrchestrator["ContextOrchestrator"]:::internal
        FileToTextTransformer["FileToTextTransformer"]:::internal
        UriToObjectFactory["UriToObjectFactory"]:::internal
    end

    %% AI Layer
    subgraph "AI Subsystem"
        direction TB
        AIProvider["AIProvider"]:::ai
        ChunkPreparation["ChunkPreparation"]:::ai
        JAssistant["JAssistant"]:::ai
        Agents["Agents (various)"]:::ai
        CUrlClient["BasicCUrlAIClient"]:::ai
    end

    %% External System Adapters
    subgraph "External Adapters"
        direction TB
        JiraClient["BasicJiraClient"]:::external
        ConfluenceClient["BasicConfluence"]:::external
        BitbucketClient["BasicBitbucket"]:::external
        GithubClient["BasicGithub"]:::external
        GitLabClient["BasicGitLab"]:::external
        RallyClient["RallyClient"]:::external
        FigmaClient["BasicFigmaClient"]:::external
        FirebaseClient["BasicFirebaseCrashlytics"]:::external
        AppCenterClient["AppCenter"]:::external
        OpenAIClient["BasicOpenAI"]:::external
    end

    %% Reporting & Output
    subgraph "Reporting & Output"
        direction TB
        FtlTemplates["Freemarker Templates"]:::output
        ReportModule["Report Modules"]:::output
        PdfClient["PdfAsTrackerClient"]:::output
    end

    %% Chrome Extension UI
    subgraph "Chrome Extension UI"
        direction TB
        ChromeManifest["manifest.json"]:::ui
        Popup["popup.html/js"]:::ui
        Settings["settings.html/js"]:::ui
    end

    %% Connections
    DMTools --> UrlEncodedJobTrigger
    UrlEncodedJobTrigger --> JobRunner
    JobRunner --> DIContainer

    DIContainer --> AbstractJob
    DIContainer --> ContextOrchestrator
    DIContainer --> AIProvider
    DIContainer --> JiraClient
    DIContainer --> ReportModule

    AbstractJob --> JobInterface
    AbstractJob --> BaseJobParams
    JobInterface --> JobParams

    ContextOrchestrator --> FileToTextTransformer
    ContextOrchestrator --> UriToObjectFactory

    AIProvider --> ChunkPreparation
    AIProvider --> JAssistant
    AIProvider --> CUrlClient
    JAssistant --> Agents

    %% Adapters connecting to AI or reporting flows
    AbstractJob --> JiraClient
    AbstractJob --> GithubClient
    AbstractJob --> GitLabClient
    AbstractJob --> BitbucketClient
    AbstractJob --> RallyClient
    AbstractJob --> ConfluenceClient
    AbstractJob --> FigmaClient
    AbstractJob --> FirebaseClient
    AbstractJob --> AppCenterClient
    AbstractJob --> OpenAIClient

    ReportModule --> FtlTemplates
    ReportModule --> PdfClient

    %% Chrome extension consumes reports
    ReportModule --> Popup
    Settings --> ReportModule

    %% Click Events
    click DMTools "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/DMTools.java"
    click UrlEncodedJobTrigger "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/job/UrlEncodedJobTrigger.java"
    click JobRunner "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/job/JobRunner.java"
    click DIContainer "https://github.com/istin/dmtools/tree/main/src/main/java/com/github/istin/dmtools/di/"
    click AbstractJob "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/job/AbstractJob.java"
    click BaseJobParams "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/job/BaseJobParams.java"
    click JobInterface "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/job/Job.java"
    click JobParams "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/job/JobParams.java"
    click ContextOrchestrator "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/context/ContextOrchestrator.java"
    click FileToTextTransformer "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/context/FileToTextTransformer.java"
    click UriToObjectFactory "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/context/UriToObjectFactory.java"
    click AIProvider "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/ai/AIProvider.java"
    click ChunkPreparation "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/ai/ChunkPreparation.java"
    click JAssistant "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/ai/JAssistant.java"
    click Agents "https://github.com/istin/dmtools/tree/main/src/main/java/com/github/istin/dmtools/ai/agent/"
    click CUrlClient "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/ai/curl/BasicCUrlAIClient.java"
    click JiraClient "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/atlassian/jira/BasicJiraClient.java"
    click ConfluenceClient "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/atlassian/confluence/BasicConfluence.java"
    click BitbucketClient "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/atlassian/bitbucket/BasicBitbucket.java"
    click GithubClient "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/github/BasicGithub.java"
    click GitLabClient "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/gitlab/BasicGitLab.java"
    click RallyClient "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/broadcom/rally/RallyClient.java"
    click FigmaClient "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/figma/BasicFigmaClient.java"
    click FirebaseClient "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/firebase/BasicFirebaseCrashlytics.java"
    click AppCenterClient "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/microsoft/AppCenter.java"
    click OpenAIClient "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/openai/BasicOpenAI.java"
    click FtlTemplates "https://github.com/istin/dmtools/tree/main/src/main/resources/ftl/"
    click ReportModule "https://github.com/istin/dmtools/tree/main/src/main/java/com/github/istin/dmtools/report/"
    click PdfClient "https://github.com/istin/dmtools/blob/main/src/main/java/com/github/istin/dmtools/pdf/PdfAsTrackerClient.java"
    click ChromeManifest "https://github.com/istin/dmtools/blob/main/chrome_extension/manifest.json"
    click Popup "https://github.com/istin/dmtools/blob/main/chrome_extension/popup.html"
    click Settings "https://github.com/istin/dmtools/blob/main/chrome_extension/settings.html"

    %% Styles
    classDef cli fill:#ffa500,stroke:#333,stroke-width:1px
    classDef internal fill:#a3be8c,stroke:#333,stroke-width:1px
    classDef external fill:#5e81ac,stroke:#333,stroke-width:1px
    classDef ai fill:#ebcb8b,stroke:#333,stroke-width:1px
    classDef output fill:#4c566a,stroke:#333,stroke-width:1px
    classDef ui fill:#d08770,stroke:#333,stroke-width:1px
```
