# dzatona/usbreset-mac architecture

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

- Interactive diagram: https://gitdiagram.com/dzatona/usbreset-mac
- Repository: https://github.com/dzatona/usbreset-mac

## Overview

##### Project Type and Purpose
- This is an open-source, command-line system utility (“usbreset”) for macOS that resets USB devices by VID:PID via Apple’s IOKit/CoreFoundation frameworks. It is organized as a modular C17 codebase with zero third-party dependencies and a full build/test/CI pipeline.

##### File Structure
- Top-level build & config:
- CMakeLists.txt, Makefile, CMakePresets.json
- .clang-format, .clang-tidy, pre-commit, GitHub workflows (ci, codeql, release)
- Source code:
- / – public headers (argument_parser.h, logging.h, usb_operations.h, error_codes.h)
- src/ – implementation modules (main.c, argument_parser.c, logging.c, usb_operations.c, error_codes.c)
- Tests:
- tests/ – unit tests + minimal framework + mocks (usb_operations_mock.c)
- Docs & examples:
- docs/usbreset.1 (man page)
- examples/usbreset.conf.example
- CI/CD:
- .github/workflows handles build, static analysis, testing, release.

##### README for Insights
- Describes modular architecture (five modules: error_codes, logging, argument_parser, usb_operations, main).
- Highlights build options (CMake presets, sanitizers, coverage).
- Describes runtime configuration: CLI flags, environment variables, config file.
- Emphasizes zero dependencies, thread safety, strict error handling.

##### Main Components & Their Relationships
- User & Environment → CLI frontend (argument_parser)
- Parses flags & VID:PID → returns structured config or error_codes
- Core Orchestrator (main.c)
- Receives parsed arguments → sets up logging → invokes usb_operations
- Receives return codes → prints status → exits with error_codes
- Submodules:
- error_codes: central repository of exit-code constants
- logging: thread-safe logger that tags all modules
- usb_operations: Layer over IOKit/CoreFoundation to find, open, reset, re-enumerate devices
- External Systems:
- Environment variables & optional config file → influence default delay & force mode
- Testing Infrastructure:
- Test harness invokes all modules in isolation, with usb_operations_mock replacing real calls
- Build/Test/Release Pipeline:
- CMake & Make compile source → generate binaries & test executables → GitHub Actions run linters, tests, coverage, and publish releases

##### Architectural Patterns & Design Principles
- Layered architecture:
- CLI Layer → Core Logic Layer → System Integration Layer
- Modular design & separation of concerns:
- Each module lives in its own package (header + implementation)
- Dependency injection for testing:
- usb_operations_mock used by test_main_coverage to isolate hardware calls
- Strict error handling & thread safety in all modules

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    User["User"]:::external

    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        AP["argument_parser\n(include/argument_parser.h,\nsrc/argument_parser.c)"]:::cli
        CFG["Config File\n(examples/usbreset.conf.example)"]:::cli
        MAN["Man Page\n(docs/usbreset.1)"]:::cli
    end

    %% Core Layer
    subgraph "Core Layer"
        direction TB
        MAIN["main\n(src/main.c)"]:::core
        LOG["logging\n(include/logging.h,\nsrc/logging.c)"]:::core
        ERR["error_codes\n(include/error_codes.h,\nsrc/error_codes.c)"]:::core
    end

    %% Integration Layer
    subgraph "System Integration Layer"
        direction TB
        USB["usb_operations\n(include/usb_operations.h,\nsrc/usb_operations.c)"]:::core
        MACOS["IOKit/CoreFoundation"]:::framework
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        BUILD["Build & Config\n(CMakeLists.txt,\nCMakePresets.json,\nMakefile)"]:::infra
        CI["CI/CD Workflows\n(.github/workflows/)"]:::infra
        TF["Test Framework\n(tests/test_framework.h,\ntests/CMakeLists.txt)"]:::infra
        TESTS["Unit Tests & Mocks\n(tests/)"]:::infra
    end

    %% Connections
    User -->|"CLI flags, env"| AP
    CFG -->|"defaults"| AP
    User -->|"requests man"| MAN
    AP -->|"parsed config"| MAIN
    MAIN -->|"init logger"| LOG
    MAIN -->|"invoke operations"| USB
    USB -->|"calls"| MACOS
    MAIN -->|"returns code"| ERR
    MAIN -->|"exit(status)"| User

    TF -->|"provides harness"| TESTS
    USB -->|"mocked by"| TESTS
    TESTS -->|"validate modules"| AP
    TESTS -->|"validate modules"| LOG
    TESTS -->|"validate modules"| ERR
    TESTS -->|"validate modules"| MAIN

    CI -->|"triggers"| BUILD
    BUILD -->|"compiles & tests"| MAIN
    BUILD -->|"compiles & tests"| TESTS
    CI -->|"runs"| TF

    %% Click Events
    click AP "https://github.com/dzatona/usbreset-mac/blob/main/include/argument_parser.h"
    click AP "https://github.com/dzatona/usbreset-mac/blob/main/src/argument_parser.c"
    click LOG "https://github.com/dzatona/usbreset-mac/blob/main/include/logging.h"
    click LOG "https://github.com/dzatona/usbreset-mac/blob/main/src/logging.c"
    click ERR "https://github.com/dzatona/usbreset-mac/blob/main/include/error_codes.h"
    click ERR "https://github.com/dzatona/usbreset-mac/blob/main/src/error_codes.c"
    click USB "https://github.com/dzatona/usbreset-mac/blob/main/include/usb_operations.h"
    click USB "https://github.com/dzatona/usbreset-mac/blob/main/src/usb_operations.c"
    click USB "https://github.com/dzatona/usbreset-mac/blob/main/tests/usb_operations_mock.c"
    click MAIN "https://github.com/dzatona/usbreset-mac/blob/main/src/main.c"
    click BUILD "https://github.com/dzatona/usbreset-mac/blob/main/CMakeLists.txt"
    click BUILD "https://github.com/dzatona/usbreset-mac/blob/main/CMakePresets.json"
    click BUILD "https://github.com/dzatona/usbreset-mac/tree/main/Makefile"
    click CI "https://github.com/dzatona/usbreset-mac/blob/main/.github/workflows/ci.yml"
    click CI "https://github.com/dzatona/usbreset-mac/blob/main/.github/workflows/codeql.yml"
    click CI "https://github.com/dzatona/usbreset-mac/blob/main/.github/workflows/release.yml"
    click MAN "https://github.com/dzatona/usbreset-mac/blob/main/docs/usbreset.1"
    click CFG "https://github.com/dzatona/usbreset-mac/blob/main/examples/usbreset.conf.example"
    click TF "https://github.com/dzatona/usbreset-mac/blob/main/tests/test_framework.h"
    click TF "https://github.com/dzatona/usbreset-mac/blob/main/tests/CMakeLists.txt"

    %% Styles
    classDef external fill:#ffffff,stroke:#000000;
    classDef cli fill:#ADD8E6,stroke:#000000;
    classDef core fill:#98FB98,stroke:#000000;
    classDef framework fill:#FFA500,stroke:#000000,stroke-dasharray: 5 5;
    classDef infra fill:#D3D3D3,stroke:#000000;
```
