# GitHub Bot SDK Responsibilities
## Overview
This document defines the responsibilities of components within the GitHub Bot SDK using Responsibility-Driven Design (RDD). Each component is defined by what it knows, what it does, and how it collaborates with other components to provide a clean, testable interface for GitHub App integration.
## Authentication Domain Components
### AppAuthenticator
**Responsibilities:**
- **Knows**: GitHub App ID, private key, installation mappings
- **Does**: Generates JWT tokens, obtains installation access tokens, manages token lifecycle
**Collaborators:**
- `TokenCache` (stores and retrieves cached tokens)
- `GitHubApiClient` (makes authenticated API requests)
- `KeyStore` (securely manages private keys)
**Roles:**
- **Token Provider**: Creates authentication tokens for API operations
- **Credential Manager**: Handles secure storage and rotation of secrets
- **Installation Resolver**: Maps repositories to GitHub App installations
### TokenCache
**Responsibilities:**
- **Knows**: Cached JWT and installation tokens with expiry times
- **Does**: Stores, retrieves, and evicts expired tokens
**Collaborators:**
- `AppAuthenticator` (requests token storage and retrieval)
- `TokenValidator` (validates token format and expiry)
**Roles:**
- **Performance Optimizer**: Reduces API calls by caching valid tokens
- **Expiry Manager**: Automatically handles token lifecycle and renewal
- **Memory Manager**: Controls cache size and cleanup
### InstallationResolver
**Responsibilities:**
- **Knows**: Repository-to-installation mappings, organization hierarchies
- **Does**: Determines correct installation ID for repository operations
**Collaborators:**
- `GitHubApiClient` (queries installation information)
- `ConfigurationManager` (gets app-level configuration)
**Roles:**
- **Mapping Service**: Connects repositories to their GitHub App installations
- **Hierarchy Navigator**: Understands organization and repository relationships
- **Access Controller**: Ensures operations target correct installations
## API Operations Domain Components
### GitHubApiClient
**Responsibilities:**
- **Knows**: GitHub API endpoints, request/response formats, rate limits
- **Does**: Executes HTTP requests, handles pagination, manages rate limiting
**Collaborators:**
- `AppAuthenticator` (gets authorization tokens)
- `RateLimitManager` (enforces rate limiting policies)
- `RetryHandler` (manages request retries)
- `ResponseParser` (processes API responses)
**Roles:**
- **Protocol Handler**: Manages HTTP communication with GitHub API
- **Rate Limiter**: Respects GitHub's rate limiting requirements
- **Error Handler**: Provides consistent error responses for API failures
### RateLimitManager
**Responsibilities:**
- **Knows**: Current rate limit status, reset times, request quotas
- **Does**: Tracks API usage, delays requests when limits approached, resets counters
**Collaborators:**
- `GitHubApiClient` (reports rate limit headers from responses)
- `DelayCalculator` (determines appropriate wait times)
**Roles:**
- **Throttle Controller**: Prevents API rate limit violations
- **Usage Tracker**: Monitors API consumption patterns
- **Delay Calculator**: Determines optimal wait times for rate limit recovery
### RepositoryOperations
**Responsibilities:**
- **Knows**: Repository metadata, branch information, file operations
- **Does**: Creates/updates files, manages branches, handles repository settings
**Collaborators:**
- `GitHubApiClient` (executes repository API calls)
- `ContentEncoder` (handles file content encoding/decoding)
- `BranchManager` (manages branch operations)
**Roles:**
- **Repository Manager**: Provides high-level repository operations
- **Content Handler**: Manages file creation, updates, and deletions
- **Branch Coordinator**: Handles branch creation and management
### PullRequestOperations
**Responsibilities:**
- **Knows**: Pull request metadata, review states, merge strategies
- **Does**: Creates/updates PRs, manages reviews, handles merge operations
**Collaborators:**
- `GitHubApiClient` (executes PR API calls)
- `ReviewManager` (handles review requests and approvals)
- `MergeStrategy` (determines appropriate merge approach)
**Roles:**
- **PR Lifecycle Manager**: Handles complete PR workflow
- **Review Coordinator**: Manages review requests and responses
- **Merge Controller**: Handles PR merge operations safely
### IssueOperations
**Responsibilities:**
- **Knows**: Issue metadata, labels, assignees, comments, milestones, reactions, lock state
- **Does**: Creates/updates issues, manages comments (with auto-pagination), handles assignees,
labels, reactions, locking, milestones, and timeline/activity-event retrieval
**Collaborators:**
- `GitHubApiClient` (executes issue API calls)
- `PaginationHelper` (drives auto-pagination loop for comment/event/reaction lists)
**Roles:**
- **Issue Lifecycle Manager**: Handles the complete issue workflow (open → close)
- **Comment Manager**: Creates, updates, deletes, and paginated-lists issue comments
- **Moderation Controller**: Locks and unlocks issues via the admin lock API
- **Assignment Coordinator**: Adds, removes, and queries assignees per-issue
- **Label Coordinator**: Adds, removes, replaces, and queries labels on issues
- **Reaction Handler**: Creates, lists, and deletes emoji reactions on issues and comments
- **Milestone CRUD**: Creates, updates, deletes, and lists milestones in a repository
- **Timeline Reader**: Retrieves complete issue activity events and full timeline for audit trails
### ReactionOperations
**Responsibilities:**
- **Knows**: Emoji reaction content types, reaction IDs, per-user reaction state
- **Does**: Creates (idempotently), lists (auto-paginated), and deletes reactions on
issues and issue comments
**Collaborators:**
- `GitHubApiClient` (executes reaction API calls)
- `PaginationHelper` (drives auto-pagination)
**Roles:**
- **Signal Emitter**: Provides lightweight emoji acknowledgements without comment noise
- **Idempotency Handler**: Treats HTTP 200 (duplicate) and HTTP 201 (new) as identical success
- **Knows**: Issue metadata, labels, assignees, comments
- **Does**: Creates/updates issues, manages labels, handles assignments
**Collaborators:**
- `GitHubApiClient` (executes issue API calls)
- `LabelManager` (manages issue labeling)
- `AssignmentManager` (handles issue assignments)
**Roles:**
- **Issue Lifecycle Manager**: Handles complete issue workflow
- **Label Coordinator**: Manages consistent labeling strategies
- **Assignment Controller**: Handles issue assignment and notifications
## Event Processing Domain Components
### WebhookValidator
**Responsibilities:**
- **Knows**: Webhook secret, signature algorithms, payload formats
- **Does**: Validates webhook signatures, verifies payload integrity
**Collaborators:**
- `SecretManager` (retrieves webhook secrets)
- `SignatureCalculator` (computes expected signatures)
- `PayloadParser` (processes webhook payloads)
**Roles:**
- **Security Gatekeeper**: Ensures webhook authenticity
- **Integrity Validator**: Verifies payload hasn't been tampered with
- **Format Checker**: Validates webhook payload structure
### EventProcessor
**Responsibilities:**
- **Knows**: Event types, processing strategies, handler mappings
- **Does**: Routes events to handlers, manages processing lifecycle
**Collaborators:**
- `EventRouter` (determines appropriate handlers)
- `EventHandler` (processes specific event types)
- `ProcessingContext` (maintains event processing state)
**Roles:**
- **Event Dispatcher**: Routes events to appropriate handlers
- **Lifecycle Manager**: Manages event processing from start to finish
- **Context Provider**: Maintains processing context across operations
### EventRouter
**Responsibilities:**
- **Knows**: Event type mappings, handler registrations, routing rules
- **Does**: Determines which handlers should process specific events
**Collaborators:**
- `EventProcessor` (requests routing decisions)
- `HandlerRegistry` (maintains handler mappings)
- `FilterChain` (applies event filtering rules)
**Roles:**
- **Traffic Director**: Determines event processing paths
- **Handler Selector**: Chooses appropriate handlers for events
- **Filter Coordinator**: Applies filtering and routing rules
## Infrastructure Domain Components
### ConfigurationManager
**Responsibilities:**
- **Knows**: App configuration, environment settings, feature flags
- **Does**: Loads configuration, validates settings, provides config access
**Collaborators:**
- `EnvironmentReader` (reads environment variables)
- `ConfigValidator` (validates configuration completeness)
- `SecretResolver` (resolves secret references)
**Roles:**
- **Configuration Provider**: Supplies configuration to all components
- **Environment Adapter**: Handles different deployment environments
- **Validation Controller**: Ensures configuration completeness and correctness
### SecretManager
**Responsibilities:**
- **Knows**: Secret storage locations, encryption keys, access policies
- **Does**: Securely stores and retrieves secrets, manages secret rotation
**Collaborators:**
- `KeyVaultAdapter` (integrates with external secret stores)
- `EncryptionProvider` (handles secret encryption/decryption)
- `AccessController` (enforces secret access policies)
**Roles:**
- **Secret Custodian**: Manages secure secret storage and access
- **Encryption Manager**: Handles secret encryption and decryption
- **Access Guardian**: Enforces secret access control policies
### TracingManager
**Responsibilities:**
- **Knows**: Trace contexts, span hierarchies, correlation IDs
- **Does**: Creates spans, propagates context, manages trace lifecycle
**Collaborators:**
- `SpanProcessor` (processes and exports spans)
- `ContextPropagator` (manages trace context propagation)
- `AttributeManager` (manages span attributes and metadata)
**Roles:**
- **Observability Provider**: Enables distributed tracing across operations
- **Context Manager**: Maintains trace context across async boundaries
- **Metadata Collector**: Gathers and organizes trace metadata
## Error Handling Components
### ErrorClassifier
**Responsibilities:**
- **Knows**: Error categories, retry policies, severity levels
- **Does**: Classifies errors, determines retry strategies, assigns severity
**Collaborators:**
- `RetryHandler` (gets retry policy recommendations)
- `LoggingManager` (reports error classifications)
- `AlertManager` (triggers alerts for critical errors)
**Roles:**
- **Error Categorizer**: Classifies errors into actionable categories
- **Retry Advisor**: Recommends appropriate retry strategies
- **Severity Assessor**: Determines error impact and urgency
### RetryHandler
**Responsibilities:**
- **Knows**: Retry policies, backoff strategies, circuit breaker states
- **Does**: Executes retry logic, manages backoff delays, controls circuit breakers
**Collaborators:**
- `ErrorClassifier` (gets error retry recommendations)
- `DelayCalculator` (computes backoff delays)
- `CircuitBreaker` (manages circuit breaker state)
**Roles:**
- **Resilience Provider**: Handles transient failures gracefully
- **Backoff Manager**: Implements appropriate delay strategies
- **Circuit Controller**: Prevents cascading failures
## Component Collaboration Matrix
| AppAuthenticator | TokenCache, GitHubApiClient, KeyStore | Token generation and caching |
| GitHubApiClient | AppAuthenticator, RateLimitManager, RetryHandler | Authenticated API requests |
| RepositoryOperations | GitHubApiClient, ContentEncoder, BranchManager | Repository management |
| WebhookValidator | SecretManager, SignatureCalculator | Webhook verification |
| EventProcessor | EventRouter, EventHandler, ProcessingContext | Event dispatching |
| ConfigurationManager | EnvironmentReader, SecretResolver | Configuration loading |
## Responsibility Boundaries
### Clear Separations
- **Authentication vs. API Operations**: Authentication components only handle tokens; API components handle requests
- **Event Processing vs. Business Logic**: Event processing routes and validates; business logic in handlers
- **Configuration vs. Secrets**: Configuration manages settings; secrets handle sensitive data separately
- **Error Handling vs. Business Operations**: Error handling is cross-cutting; business operations focus on GitHub API
### Shared Responsibilities
- **Observability**: All components participate in tracing and logging
- **Error Handling**: All components use consistent error classification and retry patterns
- **Configuration**: All components depend on configuration but don't manage it directly
## Testing Strategies by Component
### Unit Testing Focus
- **Authentication**: Token generation, caching, expiry logic
- **API Operations**: Request construction, response parsing, error handling
- **Event Processing**: Routing logic, validation, handler selection
- **Configuration**: Loading, validation, environment adaptation
### Integration Testing Focus
- **API Client + Authentication**: End-to-end authenticated requests
- **Event Processing + Webhook Validation**: Complete webhook processing pipeline
- **Configuration + Secrets**: Real environment configuration loading
### Contract Testing Focus
- **GitHub API Operations**: Verify API contract compliance
- **Webhook Processing**: Validate GitHub webhook format expectations
## Commit Operations Components
### CommitOperations (methods on InstallationClient)
**Responsibilities:**
- **Knows**: GitHub API commit endpoints, commit query parameters, comparison ref syntax, pagination rules
- **Does**: Retrieves commit details, lists commits with filters, compares refs, parses responses, maps errors
**Collaborators:**
- `InstallationClient` (uses HTTP methods and authentication)
- `ApiError` (maps HTTP status to error types)
- `IssueUser` (reuses for author/committer GitHub user associations)
**Roles:**
- **Repository Historian**: Provides access to repository commit history
- **API Gateway**: Translates domain requests to GitHub API calls
- **Validation Guardian**: Validates ref formats before API calls
**Operations:**
1. **get_commit(owner, repo, sha)** - Retrieve single commit by SHA/ref
2. **list_commits(owner, repo, filters...)** - List commits with pagination and filtering
3. **compare_commits(owner, repo, base, head)** - Compare two refs and return commits/files between them
### Commit (Domain Type)
**Responsibilities:**
- **Knows**: Commit SHA, metadata, parent commits, tree reference, verification status, GitHub user associations
- **Does**: Serializes/deserializes from GitHub API JSON, provides type-safe access to commit data
**Collaborators:**
- `CommitDetails` (nested Git-level commit information)
- `IssueUser` (GitHub user for author/committer if email matches)
- `CommitReference` (parent commits and tree references)
**Roles:**
- **Data Transfer Object**: Carries commit information from API to application
- **Type Safety Provider**: Ensures typed access to commit data
### Comparison (Domain Type)
**Responsibilities:**
- **Knows**: Base commit, head commit, merge base, status, commit differences, file changes
- **Does**: Encapsulates complete comparison result for release automation
**Collaborators:**
- `Commit` (list of commits between refs)
- `FileChange` (list of changed files with statistics)
**Roles:**
- **Comparison Result Container**: Single response for "what changed between two refs"
- **Release Automation Enabler**: Provides all data for changelog generation