architecture.puml

@startuml architecture
!theme plain
skinparam backgroundColor #FEFEFE
skinparam defaultFontName "Helvetica"
skinparam componentStyle rectangle
skinparam padding 8
skinparam ArrowColor #555555
skinparam NoteBackgroundColor #FFFFDD

title Git Hygiene — Architecture Overview

actor Developer as dev
participant "GitHub" as gh #E8F5E9
box "GitHub Actions Runner (ubuntu-latest)" #F3F4F6
  participant "action.yml\n(composite action)" as action #BBDEFB
  participant "lint_commits.py" as linter #BBDEFB
end box
participant "LanguageTool API" as lt #FFF3E0
participant "Ollama\n(local)" as ollama #E1BEE7
participant "LLM API\n(remote)" as llm_remote #E8EAF6

== PR Opened / Updated ==

dev -> gh : Push commits / Open PR
gh -> action : Trigger on\npull_request event

== Setup ==

action -> action : Set up Python 3.13
action -> action : pip install llm,\nllm-ollama, requests
alt use-local-model = true
  action -> action : Setup Ollama\n(via setup-ollama action)
  action -> ollama : ollama pull {model}\n(e.g., qwen2.5:0.5b)
  ollama --> action : Model downloaded
end

== Lint Each Commit ==

action -> linter : Run lint_commits.py\n(env vars from inputs)
linter -> linter : llm.get_model(LLM_MODEL)\n(loads model via llm library)
linter -> gh : GET /repos/{owner}/{repo}/pulls/{pr}/commits
gh --> linter : List of commits (SHA + message)

loop For each commit message
  linter -> linter : Check ignore patterns\n(skip Merge, Revert)

  alt enable-grammar = true
    group Grammar Check (optional)
      linter -> lt : POST /v2/check\n{text, language}
      lt --> linter : {matches: [{message, rule, replacements}]}
      linter -> linter : Filter matches against\ncustom words dictionary
    end
  end

  group Structure Check (always runs)
    alt use-local-model = true
      linter -> ollama : model.prompt(message,\nsystem=SYSTEM_PROMPT)\n(via llm-ollama plugin)
      ollama --> linter : JSON response
    else Remote API
      linter -> llm_remote : model.prompt(message,\nsystem=SYSTEM_PROMPT)\n(OpenAI / Anthropic / etc.)
      llm_remote --> linter : JSON response
    end
    linter -> linter : Parse LLM response:\n{explains_why, score,\nfeedback, suggestion}
  end

  linter -> linter : Collect CommitIssue results
end

== Report ==

linter -> linter : build_report()\n(Markdown summary)
linter -> gh : POST /repos/{owner}/{repo}/issues/{pr}/comments\n(create or update PR comment)

alt Issues found AND fail-on-error = true
  linter -> action : exit 1 (fail the check)
else No issues
  linter -> action : exit 0 (pass)
end

action --> gh : Check status ✅ or ❌

note right of linter
  **Local Development:**
  lint_local.py provides
  the same functionality
  for local git repos
  (no GitHub integration)
end note

@enduml