InnerSource Measurement Tool - Architecture Documentation

Overview

The InnerSource Measurement Tool is designed to analyze GitHub repositories and measure the level of cross-team collaboration (InnerSource) happening within them. This document provides detailed architectural information for developers and contributors.

System Architecture

Component Diagram

┌─────────────────────────────────────────────────────────────────────────────────┐
│                        InnerSource Measurement Tool                             │
│                                                                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │   Environment   │  │  Authentication │  │  Report Writer  │  │  Markdown   │ │
│  │  Configuration  │  │     Manager     │  │                 │  │   Helpers   │ │
│  │   (config.py)   │  │   (auth.py)     │  │(markdown_writer │  │(markdown_   │ │
│  │                 │  │                 │  │     .py)        │  │helpers.py)  │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  └─────────────┘ │
│                                      │                                          │
│  ┌─────────────────────────────────────────────────────────────────────────────┐ │
│  │                   Core Analysis Engine                                      │ │
│  │                 (measure_innersource.py)                                   │ │
│  │                                                                             │ │
│  │  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐  ┌─────────────┐ │ │
│  │  │ Repository    │  │ Organization  │  │ Team Boundary │  │ Contribution│ │ │
│  │  │ Data Fetcher  │  │ Data Loader   │  │ Detector      │  │ Analyzer    │ │ │
│  │  └───────────────┘  └───────────────┘  └───────────────┘  └─────────────┘ │ │
│  └─────────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘
                                        │
                                        ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                           External Dependencies                                 │
│                                                                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │
│  │   GitHub API    │  │  File System    │  │  org-data.json  │  │  Output     │ │
│  │                 │  │                 │  │                 │  │  Files      │ │
│  │ • Repositories  │  │ • Read/Write    │  │ • Org Structure │  │ • Markdown  │ │
│  │ • Commits       │  │ • File Handling │  │ • Manager Data  │  │ • Reports   │ │
│  │ • Pull Requests │  │                 │  │                 │  │             │ │
│  │ • Issues        │  │                 │  │                 │  │             │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  └─────────────┘ │
└─────────────────────────────────────────────────────────────────────────────────┘

Core Components

1. Configuration Management (`config.py`)

Responsibilities:

Parse and validate environment variables
Provide type-safe configuration access
Handle default values and required parameters
Support multiple authentication methods

2. Authentication Manager (`auth.py`)

Responsibilities:

Authenticate with GitHub using multiple methods
Handle GitHub Enterprise Server installations
Manage JWT tokens for GitHub App authentication
Provide unified authentication interface

3. Core Analysis Engine (`measure_innersource.py`)

Responsibilities:

Orchestrate the entire analysis process
Implement team boundary detection algorithm
Manage chunked processing for large repositories
Calculate InnerSource metrics and ratios

4. Report Generation (`markdown_writer.py`)

Responsibilities:

Generate structured Markdown reports
Format data for human consumption
Handle edge cases and missing data
Provide consistent report structure

5. Utility Functions (`markdown_helpers.py`)

Responsibilities:

Manage file size constraints
Split large files intelligently
Preserve content integrity during splits

Data Flow Architecture

Processing Pipeline

┌─────────────────┐
│  Start Process  │
└─────────────────┘
          │
          ▼
┌─────────────────┐
│ Load & Validate │
│ Configuration   │
└─────────────────┘
          │
          ▼
┌─────────────────┐
│ Authenticate    │
│ with GitHub     │
└─────────────────┘
          │
          ▼
┌─────────────────┐
│ Fetch Repository│
│ Metadata        │
└─────────────────┘
          │
          ▼
┌─────────────────┐
│ Load org-data   │
│ .json File      │
└─────────────────┘
          │
          ▼
┌─────────────────┐
│ Determine Team  │
│ Boundaries      │
└─────────────────┘
          │
          ▼
┌─────────────────┐
│ Analyze Commits │
│ (Chunked)       │
└─────────────────┘
          │
          ▼
┌─────────────────┐
│ Analyze PRs     │
│ (Chunked)       │
└─────────────────┘
          │
          ▼
┌─────────────────┐
│ Analyze Issues  │
│ (Chunked)       │
└─────────────────┘
          │
          ▼
┌─────────────────┐
│ Calculate       │
│ Metrics         │
└─────────────────┘
          │
          ▼
┌─────────────────┐
│ Generate Report │
└─────────────────┘
          │
          ▼
┌─────────────────┐
│ Handle File     │
│ Size Limits     │
└─────────────────┘
          │
          ▼
┌─────────────────┐
│ Output Results  │
└─────────────────┘

Error Handling

Error Categories

Configuration Errors: Missing or invalid environment variables
Authentication Errors: Invalid tokens or insufficient permissions
Network Errors: API timeouts or connectivity issues
Data Errors: Missing org-data.json or invalid format
Processing Errors: Unexpected data structures or edge cases

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!