# dst03106/issue-collector architecture

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

- Interactive diagram: https://gitdiagram.com/dst03106/issue-collector
- Repository: https://github.com/dst03106/issue-collector

## Overview

##### Project Type and Purpose
- This is an open-source, automated newsletter service (“IssueCollector”) that curates GitHub issues for contributor-friendly projects and delivers a periodic email.
- It can run interactively via an n8n workflow (Option 1) or fully automated on GitHub Actions (Option 2), using Node.js scripts, a Dockerized “lambda” package, and external APIs (GitHub, OpenRouter AI, DeepWiki, Gmail SMTP).

##### File Structure
Top level:
- .github/workflows/
– CI/CD pipelines to build/deploy the Docker image and to schedule/trigger the newsletter run via n8n CLI.
- lambda/
– A Docker context holding `index.js` (the entrypoint), `cli.sh` (wrapper), `Dockerfile` and `Dockerfile.local`. This packages the Node.js “function” that n8n uses.
- n8n.json
– The exported n8n workflow definition (graph of nodes).
- resources/
– A collection of JS modules, each implementing a function or LangChain agent (e.g., fetch issues, analyze root cause, generate titles, convert MJML to HTML, etc.).
- scripts/
– Tooling to import the workflow (`import-workflow.js`), build temp dirs, and shell entrypoints for local development.

##### README for Additional Insights
- Describes two execution modes, required secrets (GitHub token, OpenRouter key, Google App password), and high-level flow: load repo info → fetch issues → analyze with AI agents → assemble HTML newsletter → send email.
- Mentions use of GitHub Actions to schedule runs and AWS ECR as the Docker registry (inferred from deploy-to-aws-ecr.yml).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI/CD Layer
    subgraph "CI/CD (GitHub Actions)" 
        style CI_CD fill:#D0E8FF,stroke:#0366D6,stroke-width:2px
        BuildDeploy["Build & Deploy Job"]:::infra
        RunCLI["Run n8n CLI Job (cron)"]:::infra
    end

    %% Registry
    AWS_ECR["AWS ECR (Docker Registry)"]:::infra

    %% Containerized Runtime
    subgraph "Containerized Runtime"
        style ContainerRuntime fill:#E6FFEA,stroke:#22863A,stroke-width:2px
        Container["Docker Image\n(n8n CLI + Node.js + lambda code)"]:::container
        
        subgraph "n8n Workflow Execution"
            style N8NExec fill:#FFF5E1,stroke:#DBAB09,stroke-width:2px
            N8NEngine["n8n Engine"]:::container
            subgraph "Resource Modules"
                style Resources fill:#FFF9E8,stroke:#D29922,stroke-width:1px
                LoadRepo["Load Repo Info"]:::code
                GetIssue["Get Issue from GitHub"]:::code
                TopFit["Get Top Fit Issues"]:::code
                DeepWikiAgent["DeepWiki Agent"]:::code
                DeepWikiSchema["DeepWiki Response Schema"]:::code
                IssueAnalysisAgent["Issue Analysis Agent"]:::code
                IssueAnalysisSchema["Issue Analysis Schema"]:::code
                TitleGenAgent["Title Generator Agent"]:::code
                TitleGenSchema["Title Generator Schema"]:::code
                GetFreeModels["Get Free Models"]:::code
                ModelSelector["Model Selector"]:::code
                ConvertMJMLHelper["Convert MJML Helper"]:::code
                ConvertMJML["Convert MJML → HTML"]:::code
                SendEmailModule["Send Email Module"]:::code
            end
        end
    end

    %% External Services
    subgraph "External Services"
        style External fill:#F0F0F0,stroke:#6A737D,stroke-width:1px
        GitHubAPI["GitHub REST API"]:::external
        OpenRouterAPI["OpenRouter AI API"]:::external
        DeepWikiAPI["DeepWiki Content API"]:::external
        GmailSMTP["Gmail SMTP"]:::external
    end

    %% Delivery
    UserInbox["User Email Inbox"]:::external

    %% Workflow Definition & Tooling
    WorkflowDef["n8n Workflow Definition\n(n8n.json)"]:::code
    ImportWF["Import Workflow Script"]:::code

    %% Support Scripts
    EntryPoint["Local Dev Entrypoint"]:::code
    TempDir["Temp Dir Builder"]:::code
    WorkflowBuilder["Workflow Builder Utils"]:::code
    ConfigUtils["Other Config Utils"]:::code

    %% Connections
    BuildDeploy -->|builds image| AWS_ECR
    RunCLI -->|pulls image & runs| Container
    Container --> N8NEngine
    N8NEngine -->|executes| LoadRepo
    N8NEngine --> GetIssue
    N8NEngine --> TopFit
    N8NEngine --> DeepWikiAgent
    N8NEngine --> IssueAnalysisAgent
    N8NEngine --> TitleGenAgent
    N8NEngine --> ConvertMJML
    N8NEngine --> SendEmailModule

    LoadRepo -->|HTTP| GitHubAPI
    GetIssue -->|HTTP| GitHubAPI
    TopFit -->|logic| GetFreeModels
    DeepWikiAgent -->|HTTP| DeepWikiAPI
    DeepWikiAgent --> DeepWikiSchema
    IssueAnalysisAgent -->|HTTP| OpenRouterAPI
    IssueAnalysisAgent --> IssueAnalysisSchema
    TitleGenAgent -->|HTTP| OpenRouterAPI
    TitleGenAgent --> TitleGenSchema
    ConvertMJML -->|transform| ConvertMJMLHelper
    SendEmailModule -->|SMTP| GmailSMTP
    GmailSMTP -->|delivers| UserInbox

    %% Optional Workflow Import Path
    ImportWF -->|imports| WorkflowDef

    %% Support Scripts connections
    EntryPoint --> ImportWF
    EntryPoint --> TempDir
    TempDir --> WorkflowBuilder
    WorkflowBuilder --> ConfigUtils

    %% Click Events
    click BuildDeploy "https://github.com/dst03106/issue-collector/blob/main/.github/workflows/deploy-to-aws-ecr.yml"
    click RunCLI "https://github.com/dst03106/issue-collector/blob/main/.github/workflows/run-n8n-cli.yml"
    click Container "https://github.com/dst03106/issue-collector/tree/main/lambda/Dockerfile"
    click Container "https://github.com/dst03106/issue-collector/blob/main/lambda/Dockerfile.local"
    click Container "https://github.com/dst03106/issue-collector/blob/main/lambda/index.js"
    click Container "https://github.com/dst03106/issue-collector/blob/main/lambda/cli.sh"
    click WorkflowDef "https://github.com/dst03106/issue-collector/blob/main/n8n.json"
    click ImportWF "https://github.com/dst03106/issue-collector/blob/main/scripts/import-workflow.js"
    click LoadRepo "https://github.com/dst03106/issue-collector/blob/main/resources/load-repo-info.js"
    click GetIssue "https://github.com/dst03106/issue-collector/blob/main/resources/get-issue-from-github.js"
    click TopFit "https://github.com/dst03106/issue-collector/blob/main/resources/get-top-fit-issues.js"
    click DeepWikiAgent "https://github.com/dst03106/issue-collector/blob/main/resources/deepwiki-langchain-agent.js"
    click DeepWikiSchema "https://github.com/dst03106/issue-collector/blob/main/resources/deepwiki-response-schema.js"
    click IssueAnalysisAgent "https://github.com/dst03106/issue-collector/blob/main/resources/issue-analysis-langchain-agent.js"
    click IssueAnalysisSchema "https://github.com/dst03106/issue-collector/blob/main/resources/issue-analysis-schema.js"
    click TitleGenAgent "https://github.com/dst03106/issue-collector/blob/main/resources/title-generator-langchain-agent.js"
    click TitleGenSchema "https://github.com/dst03106/issue-collector/blob/main/resources/title-generator-schema.js"
    click GetFreeModels "https://github.com/dst03106/issue-collector/blob/main/resources/get-free-models.js"
    click ModelSelector "https://github.com/dst03106/issue-collector/blob/main/resources/modelselector.js"
    click ConvertMJMLHelper "https://github.com/dst03106/issue-collector/blob/main/resources/convert-mjml.js"
    click ConvertMJML "https://github.com/dst03106/issue-collector/blob/main/resources/convert-mjml-to-html.js"
    click SendEmailModule "https://github.com/dst03106/issue-collector/blob/main/resources/send-email.js"
    click EntryPoint "https://github.com/dst03106/issue-collector/blob/main/scripts/entrypoint.sh"
    click TempDir "https://github.com/dst03106/issue-collector/blob/main/scripts/config/temp-dir.js"
    click WorkflowBuilder "https://github.com/dst03106/issue-collector/blob/main/scripts/lib/workflow-builder.js"
    click ConfigUtils "https://github.com/dst03106/issue-collector/tree/main/scripts/config/"

    %% Styles
    classDef infra fill:#D0E8FF,stroke:#0366D6
    classDef container fill:#E6FFEA,stroke:#22863A
    classDef code fill:#FFF9E8,stroke:#D29922
    classDef external fill:#F0F0F0,stroke:#6A737D,stroke-dasharray: 2 2
```
