# n8io/ghin architecture

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

- Interactive diagram: https://gitdiagram.com/n8io/ghin
- Repository: https://github.com/n8io/ghin

## Overview

##### Project Type and Purpose
- This is a TypeScript client-library (an open-source wrapper) for the GHIN (Golfer Handicap Index Network) REST API.
- It provides a strongly-typed interface (GhinClient) to fetch handicaps, scores, player searches, etc., and supports pluggable caching and request layers.

##### File-Structure Analysis
- Top-level:
- src/client – contains the public‐facing client modules
– ghin/… – the GHIN-specific client API and models
– in-memory-cache-client – simple cache strategy implementation
– request-client – HTTP layer, authentication, token refresh
- src/models – shared type definitions and validation logic
- playground.ts – example usage
- config files (.env.example, tsconfig.json, package.json, CI workflows)

##### Architecture Overview
Main Components:
A. GhinClient (public API)
B. RequestClient (HTTP transport + auth/token management)
C. CacheClient (optional, in-memory or custom)
D. Models (request/response schemas for golfers, handicaps, scores)
E. External GHIN REST API

Interactions:
1. Consumer calls GhinClient methods (e.g., .handicaps.getOne())
2. GhinClient builds request DTO using Models
3. GhinClient delegates to RequestClient (checks authentication, issues HTTP)
4. RequestClient may consult CacheClient (cache hit? skip HTTP)
5. RequestClient issues HTTP to External GHIN API, returns response
6. GhinClient transforms raw JSON into typed Models and returns to consumer

##### Architectural Patterns & Principles
- Separation of Concerns:
- GhinClient handles domain logic,
- RequestClient handles HTTP/auth,
- CacheClient handles caching concerns,
- Models define schema/validation.
- Dependency Injection: clients and cache combos are injected at GhinClient construction.
- Single Responsibility: each folder/module has one clear purpose.

a. Components
- Consumer (your application code)
- GhinClient (lib entrypoint)
- RequestClient (HTTP + Auth)
- CacheClient (InMemoryCacheClient or custom)
- GHIN REST API (external service)
- Models package

b. Relationships & Data Flow

c. Tech & Frameworks
- TypeScript (tsconfig.json)
- Node (npm/ pnpm)
- HTTP library (fetch/axios inside RequestClient)
- In-memory cache implementation
- CI/CD (GitHub Actions workflows)

## Diagram (Mermaid)

```mermaid
flowchart TB
    Consumer["Consumer App"]:::consumer
    Playground["Playground Example"]:::internal

    subgraph "ghin Library"
        ClientEntrypoint["Client Entrypoint"]:::internal
        GhinClient["GhinClient"]:::internal

        subgraph "Models"
            SharedModels["Shared Models"]:::internal
            GhinModels["GHIN-specific Models"]:::internal
            Golfers["Golfers DTOs"]:::internal
            Handicaps["Handicaps DTOs"]:::internal
            Scores["Scores DTOs"]:::internal
        end

        subgraph "Request & Cache"
            RequestClient["RequestClient"]:::internal
            CacheClientDefault["InMemory CacheClient"]:::internal
            CacheClientInterface["CacheClient Interface"]:::internal
        end
    end

    External["GHIN REST API"]:::external

    Consumer -->|1| ClientEntrypoint
    ClientEntrypoint -->|2| GhinClient
    GhinClient -->|3| SharedModels
    GhinClient -->|4| GhinModels
    GhinModels -->|4a| Golfers
    GhinModels -->|4b| Handicaps
    GhinModels -->|4c| Scores
    GhinClient -->|5| RequestClient
    RequestClient <-->|"6 Cache Check/Store"| CacheClientDefault
    RequestClient <-->|"6 Interface"| CacheClientInterface
    RequestClient -->|7| External
    External -->|8| RequestClient
    RequestClient -->|9| GhinClient
    GhinClient -->|10| Consumer
    Consumer -->|Example| Playground

    click GhinClient "https://github.com/n8io/ghin/blob/main/src/client/ghin/index.ts"
    click ClientEntrypoint "https://github.com/n8io/ghin/blob/main/src/client/index.ts"
    click RequestClient "https://github.com/n8io/ghin/blob/main/src/client/request-client/index.ts"
    click CacheClientDefault "https://github.com/n8io/ghin/blob/main/src/client/in-memory-cache-client/index.ts"
    click CacheClientInterface "https://github.com/n8io/ghin/blob/main/src/models/cache-client.ts"
    click SharedModels "https://github.com/n8io/ghin/blob/main/src/models/index.ts"
    click Playground "https://github.com/n8io/ghin/blob/main/playground.ts"
    click GhinModels "https://github.com/n8io/ghin/tree/main/src/client/ghin/models"
    click Golfers "https://github.com/n8io/ghin/tree/main/src/client/ghin/models/golfers"
    click Handicaps "https://github.com/n8io/ghin/tree/main/src/client/ghin/models/handicaps"
    click Scores "https://github.com/n8io/ghin/tree/main/src/client/ghin/models/scores"

    classDef internal fill:#D0E1FF,stroke:#0366d6,stroke-width:2px
    classDef external fill:#E0E0E0,stroke:#666,stroke-width:2px
    classDef consumer fill:#D4F1C5,stroke:#228B22,stroke-width:2px
```
