# c2pa-org/easycla-bot architecture

> Architecture diagram of the GitHub repository c2pa-org/easycla-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/c2pa-org/easycla-bot
- Repository: https://github.com/c2pa-org/easycla-bot

## Overview

##### Project type and purpose
- This “C2PA and EasyCLA” repository is not a traditional codebase but a documentation/integration project. Its purpose is to embed and configure the EasyCLA service (hosted by the Linux Foundation) into C2PA GitHub repositories, enforce contributor license agreement (CLA) checks on pull requests, and guide users through the individual or corporate signing workflows.

##### File structure
- Top‐level files:
- README.md – explains the policy, workflows, and links to preview PDF agreements
- PREVIEW-C2PA_*.pdf – the individual and corporate CLA forms
- There is no native source code—this repo relies on an external GitHub App/bot (EasyCLA) plus external services (DocuSign, EasyCLA backend).

##### README for additional insights
- The README describes the runtime behavior: on every PR a bot checks coverage via EasyCLA’s API. If the user is uncovered, the bot “blocks” the PR and kicks off a DocuSign workflow. Once signed, EasyCLA stores the signature and the bot re‐runs the check to allow merging.
- Mentions integration points: GitHub (webhooks or GitHub App), EasyCLA web portal, DocuSign forms, JIRA for support.

##### Main components and interactions
a. Actors/Users
- Contributor (GitHub user)
- Corporate CLA Manager
b. GitHub ecosystem
- C2PA GitHub repository (with EasyCLA App installed)
- GitHub App / Bot (listens to PR events)
c. EasyCLA backend
- API Gateway / Service layer
- CLA database (stores signed agreements, authorized users, domains, Orgs)
- Web UI (portal for managers and contributors)
d. DocuSign service
- Hosted signing workflow when CLA is not yet signed
e. External systems
- Email notifications (via DocuSign / EasyCLA)
- JIRA (support tickets)

##### Relationships & data flows
1. Contributor opens Pull Request on C2PA repo
2. GitHub App receives “pull_request” webhook or event
3. App calls EasyCLA API to verify coverage
4. If covered → App posts “green check” status on PR
5. If not covered → App posts “block” status and returns a sign‐up URL
6. Contributor follows URL → lands on EasyCLA portal → chooses individual or corporate workflow
7. If corporate: portal triggers DocuSign request to CLA Manager → manager signs → EasyCLA updates DB
8. Once signed → user clicks “re‐run check” in PR → App rechecks via API → green check appears
9. Optionally, if issues arise → user files JIRA ticket

##### Architectural patterns & design principles
- Event‐driven webhook architecture (GitHub → CLA App → EasyCLA API)
- Externalized concerns:
- Authorization/agreements handled by EasyCLA service
- Signature capture outsourced to DocuSign
- Issue‐tracking/ support via JIRA
- Single source of truth for CLA state in EasyCLA DB

##### Technologies & frameworks
- GitHub App / GitHub Actions or Probot (for the CLA‐checking bot)
- EasyCLA platform (Linux Foundation’s CLA service)
- DocuSign (embedded signing)
- JIRA (Atlassian)
- Standard web UI (React/HTML/CSS) for EasyCLA portal

##### Final advice
- CLA states (not‐signed, pending signature, signed).
- Both individual and corporate branches of the workflow.
- Time delays (“wait a little while for check to re-run”) if useful for staging.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Swimlanes
  subgraph "User Side"
    Contributor((Contributor)):::external
    DocGuide["Documentation & Workflows Guide"]:::process
    CorpPDF["Corporate CLA Form (Preview)"]:::process
    IndPDF["Individual CLA Form (Preview)"]:::process
  end

  subgraph "GitHub Side"
    PR["Pull Request (C2PA Repo)"]:::process
    Bot["CLA Bot (GitHub App)"]:::process
    CheckOK["✅ CLA Covered"]:::success
    CheckFail["⛔ CLA Not Covered"]:::blocked
  end

  subgraph "EasyCLA Platform"
    API["EasyCLA API Gateway"]:::external
    DB[(CLA Database)]:::db
    UI["Web UI / Portal"]:::process
  end

  subgraph "DocuSign Service"
    DSRequest["DocuSign Signing Request"]:::external
    DSReview["Manager Signs CLA"]:::external
  end

  subgraph "External Support"
    Jira["JIRA Ticket"]:::external
  end

  %% Flows
  Contributor -->|"opens PR"| PR
  PR -->|"webhook: pull_request"| Bot
  Bot -->|"API: check-cla"| API
  API --> DB
  API -->|"response"| Bot

  Bot -->|covered| CheckOK
  Bot -->|not_covered| CheckFail

  CheckOK -->|"posts green check"| PR
  CheckFail -->|"posts block & URL"| PR
  PR -->|"follows sign URL"| UI

  UI -->|"choose workflow"| UI
  UI -->|"individual path"| IndPDF
  UI -->|"corporate path"| CorpPDF
  UI -->|"corporate triggers"| DSRequest

  DSRequest --> DSReview
  DSReview -->|"update signature"| DB

  Contributor -->|"re-run check"| Bot

  Contributor -->|"file issue"| Jira

  %% Click Events
  click DocGuide "https://github.com/c2pa-org/easycla-bot/blob/master/README.md"
  click CorpPDF "https://github.com/c2pa-org/easycla-bot/blob/master/PREVIEW-C2PA-Corporate-Contributor-Agreement.pdf"
  click IndPDF "https://github.com/c2pa-org/easycla-bot/blob/master/PREVIEW-C2PA_Non-Member_Agreement-Individual-Contributors.pdf"

  %% Styles
  classDef external fill:#bee3f8,stroke:#3182ce,color:#2c5282
  classDef process fill:#fefcbf,stroke:#dd6b20,color:#975a16
  classDef success fill:#c6f6d5,stroke:#2f855a,color:#22543d
  classDef blocked fill:#fed7d7,stroke:#c53030,color:#742a2a
  classDef db fill:#e2e8f0,stroke:#4a5568,color:#1a202c
```
