docs: Improve documentation with comprehensive examples, architecture details, and troubleshooting

.github/workflows/linter.yaml

@@ -35,3 +35,4 @@ jobs:
           DEFAULT_BRANCH: main
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GITHUB_ACTIONS_COMMAND_ARGS: -shellcheck=
+          VALIDATE_MARKDOWN_PRETTIER: false

ARCHITECTURE.md

@@ -0,0 +1,182 @@
+# 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
+
+```bash
+┌─────────────────────────────────────────────────────────────────────────────────┐
+│                        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
+
+```bash
+┌─────────────────┐
+│  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
+
+1. **Configuration Errors**: Missing or invalid environment variables
+2. **Authentication Errors**: Invalid tokens or insufficient permissions
+3. **Network Errors**: API timeouts or connectivity issues
+4. **Data Errors**: Missing org-data.json or invalid format
+5. **Processing Errors**: Unexpected data structures or edge cases