Architecture

Architecture

This document outlines the architecture and workflows of the githubauthlib project.

Component Architecture

---
title: Component Architecture
---
graph TB
    subgraph "Operating Systems"
        M[macOS Keychain]
        W[Windows Credential Manager]
        L[Linux libsecret]
    end

    subgraph "Core Library"
        GT[get_github_token]
        TV[TokenValidator]
        EH[ErrorHandler]
        Logger
    end

    M --> GT
    W --> GT
    L --> GT
    GT --> TV
    GT --> EH
    EH --> Logger

    style GT fill:#d8d8d8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style TV fill:#d8d8d8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style EH fill:#d8d8d8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style M fill:#e8e8e8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style W fill:#e8e8e8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style L fill:#e8e8e8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style Logger fill:#e8e8e8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a

Loading

CI/CD Pipeline Flow

flowchart TD
    PR[Pull Request] --> Tests
    
    subgraph "Quality Gates"
        Tests --> Format[Black Formatting]
        Format --> Lint[Flake8 Linting]
        Lint --> Coverage[100% Test Coverage]
        Coverage --> Security[Security Scan]
    end
    
    subgraph "SonarCloud"
        Security --> QG[Quality Gate]
        QG --> Vuln[Vulnerability Check]
        Vuln --> Maint[Maintainability Check]
    end
    
    QG --> Merge[Merge to Main]
    Merge --> Tag[Version Tag]
    Tag --> Publish[Publish to PyPI]
    
    style PR fill:#d8d8d8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style Publish fill:#d8d8d8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style Tests fill:#e8e8e8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style Format fill:#e8e8e8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style Lint fill:#e8e8e8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style Coverage fill:#e8e8e8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style Security fill:#e8e8e8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style QG fill:#d8d8d8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style Vuln fill:#e8e8e8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style Maint fill:#e8e8e8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style Merge fill:#e8e8e8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a
    style Tag fill:#e8e8e8,stroke:#2a2a2a,stroke-width:2px,color:#2a2a2a

Loading

Build and Test Process

sequenceDiagram
    Dev->>Script: Run Script
    Script->>Venv: Create & Activate
    activate Venv
    Venv->>Tests: Run Black
    Venv->>Tests: Run isort
    Venv->>Tests: Run Flake8
    Venv->>Tests: Run Pytest
    Tests-->>Script: Test Results
    Script->>Build: Build Package
    Build-->>Script: Distribution Files
    Script->>Venv: Deactivate
    deactivate Venv

Loading

PyPI Publishing Workflow

sequenceDiagram
    participant GH as GitHub
    participant GA as GitHub Actions
    participant OIDC as OIDC Provider
    participant PyPI as PyPI
    
    GH->>GA: Push Tag
    activate GA
    GA->>OIDC: Request Token
    OIDC-->>GA: Issue Token
    GA->>PyPI: Verify Publisher
    PyPI-->>GA: Confirm Trust
    GA->>PyPI: Upload Package
    PyPI-->>GA: Publish Success
    deactivate GA

Loading

Security and Authentication Flow

graph LR
    App-->Lib
    Lib-->Store
    Store-.->Git
    Git-.->API

Loading

Development Workflow

gitGraph
    commit id: "initial"
    branch feature
    checkout feature
    commit id: "implement"
    commit id: "test"
    checkout main
    merge feature
    commit id: "v1.0.0" tag: "v1.0.0"
    commit id: "fix" tag: "v1.0.1"

Loading

Directory Structure

githubauthlib/
.
├── AUXILIARY.md
├── LiICENSE
├── PYPI.md
├── README.md
├── dist
│   ├── githubauthlib-1.0.0-py3-none-any.whl
│   └── githubauthlib-1.0.0.tar.gz
├── docs
│   ├── conf.py
│   └── index.rst
├── githubauthlib
│   ├── __init__.py
│   ├── __pycache__
│   │   ├── __init__.cpython-313.pyc
│   │   └── github_auth.cpython-313.pyc
│   └── github_auth.py
├── githubauthlib.egg-info
│   ├── PKG-INFO
│   ├── SOURCES.txt
│   ├── dependency_links.txt
│   └── top_level.txt
├── htmlcov
│   ├── class_index.html
│   ├── coverage_html_cb_6fb7b396.js
│   ├── favicon_32_cb_58284776.png
│   ├── function_index.html
│   ├── index.html
│   ├── keybd_closed_cb_ce680311.png
│   ├── status.json
│   ├── style_cb_8e611ae1.css
│   ├── z_8c61774e6aa2e2d1___init___py.html
│   └── z_8c61774e6aa2e2d1_github_auth_py.html
├── requirements.txt
├── scripts
│   ├── build_and_publish.sh
│   └── test_and_lint.sh
├── setup.py
└── tests
    ├── __init__.py
    ├── __pycache__
    │   ├── __init__.cpython-313.pyc
    │   └── test_github_auth.cpython-313-pytest-8.3.4.pyc
    └── test_github_auth.py

10 directories, 34 files

Key Components

1. Core Library

   • Token retrieval from system keychains
   • Cross-platform compatibility
   • Error handling and logging

2. Build System

   • Virtual environment management
   • Dependency handling
   • Package building

3. Quality Assurance

   • Automated testing
   • Code formatting
   • Static analysis
   • Security scanning

4. CI/CD Pipeline

   • GitHub Actions automation
   • SonarCloud integration
   • PyPI trusted publishing

5. Security

   • OIDC authentication
   • Secure token handling
   • Automated vulnerability scanning