# ossf/scorecard architecture

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

- Interactive diagram: https://gitdiagram.com/ossf/scorecard
- Repository: https://github.com/ossf/scorecard

## Overview

##### Main Components

a. Core Components:
- Scorecard CLI
- Check Runner System
- Probes System
- Client Interfaces (GitHub, GitLab, Local)
- Data Storage & Publishing System
- REST API Service

b. Supporting Systems:
- Authentication Handler
- Results Formatter
- Cron Jobs System
- Monitoring System

##### Component Relationships and Data Flow

a. Primary Flow:
**User Input -> Authentication -> Repository Client -> Check Runner -> Results**

b. Secondary Flows:
- Cron System -> BigQuery Storage
- REST API -> Cached Results
- Badge System -> Score Display

##### Detailed Component Breakdown

a. Input Layer:
- Authentication handlers for different platforms
- Package manager inputs (npm, PyPI, etc.)

b. Core Processing Layer:
- Check Runner orchestrating multiple checks
- Parallel execution of security checks
- Probe system integration

c. Client Layer:
- Different repository clients (GitHub, GitLab, Local)
- API rate limiting and token management
- Webhook handling system

d. Storage Layer:
- BigQuery integration for public data
- Caching system for REST API
- Results storage and formatting

##### Specific Design Elements

- Rectangles: Core services
- Diamonds: Decision points
- Clouds: External services

- Green: Public interfaces
- Blue: Core processing
- Yellow: Authentication
- Red: Critical security components
- Gray: External dependencies

##### Implementation Details to Highlight

a. Security Features:
- Token management
- Rate limiting
- Permission checks
- Vulnerability scanning

b. Scalability Features:
- Parallel check execution
- Caching mechanisms
- Batch processing

##### External Integrations

a. Connections to:
- GitHub API
- GitLab API
- OSS-Fuzz
- OpenSSF Best Practices Badge
- OSV service

##### Monitoring and Observability

a. Include:
- Logging system
- Metrics collection
- Error tracking
- Performance monitoring

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Define styles
    classDef ui fill:#90EE90,stroke:#333,stroke-width:2px
    classDef auth fill:#FFD700,stroke:#333,stroke-width:2px
    classDef core fill:#87CEEB,stroke:#333,stroke-width:2px
    classDef storage fill:#D3D3D3,stroke:#333,stroke-width:2px
    classDef external fill:#FFA07A,stroke:#333,stroke-width:2px
    classDef monitoring fill:#DDA0DD,stroke:#333,stroke-width:2px

    %% User Interface Layer
    subgraph UI
        CLI["Scorecard CLI"]:::ui
        API["REST API Service"]:::ui
        BADGE["Badge System"]:::ui
    end
    click CLI "https://github.com/ossf/scorecard/blob/main/cmd/root.go"

    %% Authentication Layer
    subgraph AUTH
        AuthHandler["Authentication Handler"]:::auth
        TokenMgmt["Token Management"]:::auth
    end
    click AuthHandler "https://github.com/ossf/scorecard/tree/main/clients/githubrepo/roundtripper/"

    %% Core Processing Layer
    subgraph CORE
        CheckRunner["Check Runner"]:::core
        Probes["Probes System"]:::core
        SecChecks["Security Checks"]:::core
        PolicyMgr["Policy Manager"]:::core
        ErrorHandler["Error Handler"]:::core
        ConfigMgr["Config Manager"]:::core
    end
    click CheckRunner "https://github.com/ossf/scorecard/blob/main/checker/check_runner.go"
    click Probes "https://github.com/ossf/scorecard/tree/main/probes/"
    click SecChecks "https://github.com/ossf/scorecard/tree/main/checks/"
    click PolicyMgr "https://github.com/ossf/scorecard/blob/main/policy/policy.go"
    click ErrorHandler "https://github.com/ossf/scorecard/tree/main/errors/"
    click ConfigMgr "https://github.com/ossf/scorecard/blob/main/config/config.go"

    %% Client Integration Layer
    subgraph CLIENTS
        GHClient["GitHub Client"]:::core
        GLClient["GitLab Client"]:::core
        LocalClient["Local Client"]:::core
        PkgClient["Package Client"]:::core
    end
    click GHClient "https://github.com/ossf/scorecard/tree/main/clients/githubrepo/"
    click GLClient "https://github.com/ossf/scorecard/tree/main/clients/gitlabrepo/"
    click LocalClient "https://github.com/ossf/scorecard/tree/main/clients/localdir/"
    click PkgClient "https://github.com/ossf/scorecard/tree/main/internal/packageclient/"

    %% Storage Layer
    subgraph STORAGE
        BigQuery[(BigQuery)]:::storage
        Cache[(Cache)]:::storage
        ResultsDB[(Results Storage)]:::storage
    end
    click ResultsDB "https://github.com/ossf/scorecard/tree/main/cron/data/"

    %% Monitoring Layer
    subgraph MONITORING
        Monitor["Monitoring System"]:::monitoring
        CronJobs["Cron Jobs"]:::monitoring
        ResultsFmt["Results Formatter"]:::monitoring
    end
    click Monitor "https://github.com/ossf/scorecard/tree/main/cron/monitoring/"
    click CronJobs "https://github.com/ossf/scorecard/tree/main/cron/"
    click ResultsFmt "https://github.com/ossf/scorecard/tree/main/pkg/scorecard/"

    %% External Services
    subgraph EXTERNAL
        GitHub["GitHub API"]:::external
        GitLab["GitLab API"]:::external
        OSSFuzz["OSS-Fuzz"]:::external
        OSV["OSV Service"]:::external
    end

    %% Relationships
    CLI --> AuthHandler
    API --> AuthHandler
    AuthHandler --> TokenMgmt
    TokenMgmt --> CLIENTS
    CLIENTS --> CheckRunner
    CheckRunner --> Probes
    CheckRunner --> SecChecks
    CheckRunner --> PolicyMgr
    Probes --> ErrorHandler
    SecChecks --> ErrorHandler
    ErrorHandler --> ResultsFmt
    ConfigMgr --> CheckRunner
    ResultsFmt --> Cache
    ResultsFmt --> BigQuery
    CronJobs --> BigQuery
    Monitor --> ResultsDB
    CLIENTS --> EXTERNAL

    %% Legend
    subgraph Legend
        UI_L["User Interface"]:::ui
        AUTH_L["Authentication"]:::auth
        CORE_L["Core Processing"]:::core
        STORAGE_L["Storage"]:::storage
        EXTERNAL_L["External Services"]:::external
        MONITORING_L["Monitoring"]:::monitoring
    end
```
