# dicodingacademy/senpai-action architecture

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

- Interactive diagram: https://gitdiagram.com/dicodingacademy/senpai-action
- Repository: https://github.com/dicodingacademy/senpai-action

## Overview

##### Project type and purpose
- From the file tree and README, this is an open‑source GitHub Action (“SenpAI”) that runs automated, AI‑powered code reviews using Google’s Gemini model. It’s not a web app or full‑stack project, but rather a CLI‑style action that plugs into GitHub’s workflow engine, reads diffs, queries Gemini, and posts comments back to PRs.

##### File structure
- Top‑level:
- `.github/workflows/*.yml` – workflow definitions that trigger the action.
- `action.yml` – action metadata (inputs, outputs, runs).
- `src/index.js` – the entry point.
- `src/lib/` – helper modules:
– `config.js` (reads inputs, sets defaults)
– `diff-parser.js` (extracts changed lines)
– `comment-parser.js` (builds comment payloads)
– `gemini-client.js` (wraps HTTP calls to Google Gemini)
– `github-client.js` (wraps GitHub REST API calls)
- `dist/index.js` – built/bundled code delivered to npm.
- `eslint.config.mjs`, `package.json` – linting and dependencies.
- `README.md` – overview & usage.

##### README for additional insights
- Describes triggers (`pull_request`, `issue_comment`), required secrets (GEMINI_API_KEY), and customization inputs (model, exclusions, tone).
- Workflow example shows how to integrate the action step.

##### Main components & relationships
a. Components:
1. GitHub Platform – hosts repo, emits events, hosts Actions runner.
2. Workflow Definition (.github/workflows) – listens for PRs or comments.
3. SenpAI Action (action.yml + dist/index.js) – the packaged action.
4. Internal Modules (at runtime in the Action container):
- Config Loader
- Diff Parser
- Gemini Client (external API)
- Comment Parser
- GitHub Client
5. External Service – Google Gemini API
6. GitHub REST API
b. Interactions / Data Flow:
1. PR opened or `/review` comment → GitHub emits event → Workflow triggers.
2. Actions runner checks out code.
3. SenpAI action starts (dist/index.js):
- Load inputs/secrets (config).
- Read PR diff (diff-parser).
- Call Google Gemini API with code snippets (gemini-client).
- Receive analysis & feedback from Gemini.
- Build line‑by‑line comments (comment-parser).
- Post comments to GitHub PR via GitHub API (github-client).
c. Architectural patterns & design principles:
- Modular library pattern: each concern (config, parsing, external calls) is isolated.
- Single‑responsibility modules.
- Facade/wrapper around external services (Gemini, GitHub) to simplify error handling and retries.
- Event‑driven flow (GitHub events trigger the action).
d. Key technologies/frameworks:
- Node.js
- GitHub Actions toolkit (action.yml conventions)
- Google Gemini REST API
- GitHub REST API v3

- Inside “Action Container,” chain: Config → Diff Parser → Gemini Client → Comment Parser → GitHub Client.
- Triggers entering the flow from the top (GitHub Event → Checkout → Action).
- Use consistent iconography (GitHub octocat, Google Gemini logo) to improve readability.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% GitHub Platform Zone
  subgraph "GitHub Platform"
    classDef github fill:#2ca02c,stroke:#000,color:#fff;
    WD1["Workflow: pr-review.yml"]:::github
    WD2["Workflow: build-and-release.yml"]:::github
    Repo["Repository Files"]:::github
    GitHubAPI["GitHub REST API"]:::github
  end

  %% Repository Files
  subgraph "Repository Files"
    actionMeta["Action Metadata (action.yml)"]:::github
    srcIndex["Source Entry (src/index.js)"]:::github
    distIndex["Bundled Entry (dist/index.js)"]:::github
    eslintCfg["ESLint Config (eslint.config.mjs)"]:::github
    pkgJSON["package.json"]:::github
    pkgLock["package-lock.json"]:::github
    readme["README.md"]:::github
    subgraph "Modules"
      configMod["Config Loader (config.js)"]:::github
      diffMod["Diff Parser (diff-parser.js)"]:::github
      geminiMod["Gemini Client (gemini-client.js)"]:::github
      commentMod["Comment Parser (comment-parser.js)"]:::github
      githubMod["GitHub Client (github-client.js)"]:::github
    end
  end

  %% Actions Runner Checkout
  Checkout["Checkout Code"] 

  %% Action Execution
  ActionDef["SenpAI Action\n(action.yml)"]:::github
  ContainerExec["Execute Bundled Code\n(dist/index.js)"] 

  %% Action Container Internals
  subgraph "Action Container"
    classDef internal fill:#1f77b4,stroke:#000,color:#fff;
    Config["Config Loader"]:::internal
    Diff["Diff Parser"]:::internal
    GeminiClient["Gemini Client"]:::internal
    CommentParser["Comment Parser"]:::internal
    GitHubClient["GitHub Client"]:::internal
  end

  %% External AI Service
  GeminiAPI["Google Gemini API"]:::external
  classDef external fill:#ff7f0e,stroke:#000,color:#fff;

  %% Connections
  WD1 -->|Event: pull_request / issue_comment| Checkout
  WD2 -->|Event: push / release| Checkout
  Checkout --> ActionDef
  ActionDef --> ContainerExec
  ContainerExec --> Config
  Config --> Diff
  Diff --> GeminiClient
  GeminiClient --> CommentParser
  CommentParser --> GitHubClient
  GeminiClient -->|HTTPS| GeminiAPI
  GitHubClient -->|REST| GitHubAPI

  %% Click Events
  click WD1 "https://github.com/dicodingacademy/senpai-action/blob/main/.github/workflows/pr-review.yml"
  click WD2 "https://github.com/dicodingacademy/senpai-action/blob/main/.github/workflows/build-and-release.yml"
  click actionMeta "https://github.com/dicodingacademy/senpai-action/blob/main/action.yml"
  click srcIndex "https://github.com/dicodingacademy/senpai-action/blob/main/src/index.js"
  click distIndex "https://github.com/dicodingacademy/senpai-action/blob/main/dist/index.js"
  click configMod "https://github.com/dicodingacademy/senpai-action/blob/main/src/lib/config.js"
  click diffMod "https://github.com/dicodingacademy/senpai-action/blob/main/src/lib/diff-parser.js"
  click geminiMod "https://github.com/dicodingacademy/senpai-action/blob/main/src/lib/gemini-client.js"
  click commentMod "https://github.com/dicodingacademy/senpai-action/blob/main/src/lib/comment-parser.js"
  click githubMod "https://github.com/dicodingacademy/senpai-action/blob/main/src/lib/github-client.js"
  click eslintCfg "https://github.com/dicodingacademy/senpai-action/blob/main/eslint.config.mjs"
  click pkgJSON "https://github.com/dicodingacademy/senpai-action/blob/main/package.json"
  click pkgLock "https://github.com/dicodingacademy/senpai-action/blob/main/package-lock.json"
  click readme "https://github.com/dicodingacademy/senpai-action/blob/main/README.md"
```
