# piomin/ai-software-factory architecture

> Architecture diagram of the GitHub repository piomin/ai-software-factory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/piomin/ai-software-factory
- Repository: https://github.com/piomin/ai-software-factory

## Overview

This repository deploys a Kubernetes/OpenShift software factory: GitHub issues and comments enter through Tekton Triggers, start one of three agent pipelines, and can produce a plan, code changes, a pull request, or a reply. Pipelines fetch skills, prepare a branch, run OpenCode against an in-cluster vLLM model, verify changes, and publish results. The graph follows documented event and pipeline flows; source excerpts were not provided, so relationships are evidenced by the README rather than inspected implementation details.

Main entry points: [`agents/Dockerfile.opencode`](https://github.com/piomin/ai-software-factory/blob/master/agents/Dockerfile.opencode) (OpenCode agent), [`tekton/pipeline-issue-agent.yaml`](https://github.com/piomin/ai-software-factory/blob/master/tekton/pipeline-issue-agent.yaml) (New issue flow), [`tekton/pipeline-issue-comment-agent.yaml`](https://github.com/piomin/ai-software-factory/blob/master/tekton/pipeline-issue-comment-agent.yaml) (Issue comment flow), [`tekton/pipeline-pr-comment-agent.yaml`](https://github.com/piomin/ai-software-factory/blob/master/tekton/pipeline-pr-comment-agent.yaml) (PR review flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Event intake"]
  node_route["Webhook route"]
  node_listener["EventListener"]
  node_hmac["HMAC interceptor"]
  node_cel["CEL filters"]
  node_binding["Trigger bindings"]
  node_template["Trigger templates"]
end

subgraph group_workflow["Agent workflows"]
  node_run["PipelineRun"]
  node_issue["New issue flow"]
  node_issuecomment["Issue comment flow"]
  node_prcomment["PR review flow"]
  node_skills["Fetch skills"]
  node_verify["Build verification"]
  node_failure["Failure reporting"]
end

subgraph group_runtime["Agent and models"]
  node_agent["OpenCode agent"]
  node_agentconfig["Agent configuration"]
  node_model["Qwen model serving"]
  node_coder["Qwen coder serving"]
end

subgraph group_access["Cluster access"]
  node_githubapp["GitHub App credentials"]
  node_webhooksecret["Webhook secret"]
  node_hftoken["Model hub token"]
end

node_github(("GitHub events"))

node_github -->|"sends webhook"| node_route
node_route -->|"routes events"| node_listener
node_listener -->|"checks signature"| node_hmac
node_listener -->|"filters events"| node_cel
node_cel -->|"maps payload"| node_binding
node_binding -->|"sets parameters"| node_template
node_template -->|"creates run"| node_run
node_run -->|"starts pipeline"| node_issue
node_run -->|"starts pipeline"| node_issuecomment
node_run -->|"starts pipeline"| node_prcomment
node_issue -->|"fetches skills"| node_skills
node_issuecomment -->|"fetches skills"| node_skills
node_prcomment -->|"fetches skills"| node_skills
node_issue -->|"runs agent"| node_agent
node_issuecomment -->|"runs agent"| node_agent
node_prcomment -->|"runs agent"| node_agent
node_issue -->|"verifies changes"| node_verify
node_issuecomment -->|"verifies changes"| node_verify
node_prcomment -->|"verifies changes"| node_verify
node_agent -->|"requests inference"| node_model
node_agentconfig -->|"configures agent"| node_agent
node_issue -->|"publishes PR and reply"| node_github
node_issuecomment -->|"publishes reply or PR"| node_github
node_prcomment -->|"publishes reply or changes"| node_github
node_listener -->|"checks secret"| node_webhooksecret
node_agent -->|"gets installation token"| node_githubapp
node_model -->|"authenticates model pull"| node_hftoken
node_agent -.->|"may use model"| node_coder
node_issue -->|"reports failure"| node_failure

click node_route "https://github.com/piomin/ai-software-factory/blob/master/tekton/route-new-issue.yaml"
click node_listener "https://github.com/piomin/ai-software-factory/blob/master/tekton/eventlistener-new-issue.yaml"
click node_hmac "https://github.com/piomin/ai-software-factory/blob/master/tekton/eventlistener-new-issue.yaml"
click node_cel "https://github.com/piomin/ai-software-factory/blob/master/tekton/eventlistener-new-issue.yaml"
click node_binding "https://github.com/piomin/ai-software-factory/blob/master/tekton/triggerbinding-new-issue.yaml"
click node_template "https://github.com/piomin/ai-software-factory/blob/master/tekton/triggertemplate-new-issue.yaml"
click node_run "https://github.com/piomin/ai-software-factory/blob/master/tekton/triggertemplate-new-issue.yaml"
click node_issue "https://github.com/piomin/ai-software-factory/blob/master/tekton/pipeline-issue-agent.yaml"
click node_issuecomment "https://github.com/piomin/ai-software-factory/blob/master/tekton/pipeline-issue-comment-agent.yaml"
click node_prcomment "https://github.com/piomin/ai-software-factory/blob/master/tekton/pipeline-pr-comment-agent.yaml"
click node_skills "https://github.com/piomin/ai-software-factory/blob/master/tekton/task-fetch-skills.yaml"
click node_verify "https://github.com/piomin/ai-software-factory/blob/master/tekton/task-verify-build.yaml"
click node_failure "https://github.com/piomin/ai-software-factory/blob/master/tekton/task-report-failure.yaml"
click node_agent "https://github.com/piomin/ai-software-factory/blob/master/agents/Dockerfile.opencode"
click node_agentconfig "https://github.com/piomin/ai-software-factory/blob/master/agents/configmap-agent-config.yaml"
click node_model "https://github.com/piomin/ai-software-factory/blob/master/ai/deployment-qwen38-flash.yaml"
click node_coder "https://github.com/piomin/ai-software-factory/blob/master/ai/deployment-qwen3-coder.yaml"
click node_githubapp "https://github.com/piomin/ai-software-factory/blob/master/secrets/secret-github-app.yaml"
click node_webhooksecret "https://github.com/piomin/ai-software-factory/blob/master/secrets/secret-github-webhook-secret.yaml"
click node_hftoken "https://github.com/piomin/ai-software-factory/blob/master/secrets/secret-hf-token.yaml"

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_route,node_listener,node_hmac,node_cel,node_binding,node_template toneBlue
class node_run,node_issue,node_issuecomment,node_prcomment,node_skills,node_verify,node_failure toneAmber
class node_agent,node_agentconfig,node_model,node_coder toneMint
class node_githubapp,node_webhooksecret,node_hftoken toneRose
class node_github toneIndigo
```

## Components

### Event intake

- [Webhook route](https://github.com/piomin/ai-software-factory/blob/master/tekton/route-new-issue.yaml): `tekton/route-new-issue.yaml`
- [EventListener](https://github.com/piomin/ai-software-factory/blob/master/tekton/eventlistener-new-issue.yaml): `tekton/eventlistener-new-issue.yaml`
- [HMAC interceptor](https://github.com/piomin/ai-software-factory/blob/master/tekton/eventlistener-new-issue.yaml): `tekton/eventlistener-new-issue.yaml`
- [CEL filters](https://github.com/piomin/ai-software-factory/blob/master/tekton/eventlistener-new-issue.yaml): `tekton/eventlistener-new-issue.yaml`
- [Trigger bindings](https://github.com/piomin/ai-software-factory/blob/master/tekton/triggerbinding-new-issue.yaml): `tekton/triggerbinding-new-issue.yaml`
- [Trigger templates](https://github.com/piomin/ai-software-factory/blob/master/tekton/triggertemplate-new-issue.yaml): `tekton/triggertemplate-new-issue.yaml`

### Agent workflows

- [PipelineRun](https://github.com/piomin/ai-software-factory/blob/master/tekton/triggertemplate-new-issue.yaml): `tekton/triggertemplate-new-issue.yaml`
- [New issue flow](https://github.com/piomin/ai-software-factory/blob/master/tekton/pipeline-issue-agent.yaml): `tekton/pipeline-issue-agent.yaml`
- [Issue comment flow](https://github.com/piomin/ai-software-factory/blob/master/tekton/pipeline-issue-comment-agent.yaml): `tekton/pipeline-issue-comment-agent.yaml`
- [PR review flow](https://github.com/piomin/ai-software-factory/blob/master/tekton/pipeline-pr-comment-agent.yaml): `tekton/pipeline-pr-comment-agent.yaml`
- [Fetch skills](https://github.com/piomin/ai-software-factory/blob/master/tekton/task-fetch-skills.yaml): `tekton/task-fetch-skills.yaml`
- [Build verification](https://github.com/piomin/ai-software-factory/blob/master/tekton/task-verify-build.yaml): `tekton/task-verify-build.yaml`
- [Failure reporting](https://github.com/piomin/ai-software-factory/blob/master/tekton/task-report-failure.yaml): `tekton/task-report-failure.yaml`

### Agent and models

- [OpenCode agent](https://github.com/piomin/ai-software-factory/blob/master/agents/Dockerfile.opencode): `agents/Dockerfile.opencode`
- [Agent configuration](https://github.com/piomin/ai-software-factory/blob/master/agents/configmap-agent-config.yaml): `agents/configmap-agent-config.yaml`
- [Qwen model serving](https://github.com/piomin/ai-software-factory/blob/master/ai/deployment-qwen38-flash.yaml): `ai/deployment-qwen38-flash.yaml`
- [Qwen coder serving](https://github.com/piomin/ai-software-factory/blob/master/ai/deployment-qwen3-coder.yaml): `ai/deployment-qwen3-coder.yaml`

### Cluster access

- [GitHub App credentials](https://github.com/piomin/ai-software-factory/blob/master/secrets/secret-github-app.yaml): `secrets/secret-github-app.yaml`
- [Webhook secret](https://github.com/piomin/ai-software-factory/blob/master/secrets/secret-github-webhook-secret.yaml): `secrets/secret-github-webhook-secret.yaml`
- [Model hub token](https://github.com/piomin/ai-software-factory/blob/master/secrets/secret-hf-token.yaml): `secrets/secret-hf-token.yaml`

### Other components

- **GitHub events**

## Connections

- GitHub events → Webhook route: sends webhook (evidence: `README.md`)
- Webhook route → EventListener: routes events (evidence: `README.md`)
- EventListener → HMAC interceptor: checks signature (evidence: `README.md`)
- EventListener → CEL filters: filters events (evidence: `README.md`)
- CEL filters → Trigger bindings: maps payload (evidence: `README.md`)
- Trigger bindings → Trigger templates: sets parameters (evidence: `README.md`)
- Trigger templates → PipelineRun: creates run (evidence: `README.md`)
- PipelineRun → New issue flow: starts pipeline (evidence: `README.md`)
- PipelineRun → Issue comment flow: starts pipeline (evidence: `README.md`)
- PipelineRun → PR review flow: starts pipeline (evidence: `README.md`)
- New issue flow → Fetch skills: fetches skills (evidence: `README.md`)
- Issue comment flow → Fetch skills: fetches skills (evidence: `README.md`)
- PR review flow → Fetch skills: fetches skills (evidence: `README.md`)
- New issue flow → OpenCode agent: runs agent (evidence: `README.md`)
- Issue comment flow → OpenCode agent: runs agent (evidence: `README.md`)
- PR review flow → OpenCode agent: runs agent (evidence: `README.md`)
- New issue flow → Build verification: verifies changes (evidence: `README.md`)
- Issue comment flow → Build verification: verifies changes (evidence: `README.md`)
- PR review flow → Build verification: verifies changes (evidence: `README.md`)
- OpenCode agent → Qwen model serving: requests inference (evidence: `README.md`)
- Agent configuration → OpenCode agent: configures agent (evidence: `README.md`)
- New issue flow → GitHub events: publishes PR and reply (evidence: `README.md`)
- Issue comment flow → GitHub events: publishes reply or PR (evidence: `README.md`)
- PR review flow → GitHub events: publishes reply or changes (evidence: `README.md`)
- EventListener → Webhook secret: checks secret (evidence: `README.md`)
- OpenCode agent → GitHub App credentials: gets installation token (evidence: `README.md`)
- Qwen model serving → Model hub token: authenticates model pull (evidence: `README.md`)
- OpenCode agent → Qwen coder serving: may use model
- New issue flow → Failure reporting: reports failure (evidence: `README.md`)
