# tfmart/scrobblekit architecture

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

- Interactive diagram: https://gitdiagram.com/tfmart/scrobblekit
- Repository: https://github.com/tfmart/scrobblekit

## Overview

##### Main Components
- SBKManager: This is the core entry point for users of the library. It exposes most of the public API methods (such as album, artist, track, chart, geo, user, etc.) and handles authentication sessions.
- Public API Layer: Represented by the modules under Sources/ScrobbleKit/Public. These modules offer the interfaces (methods for Album, Artist, Chart, Geo, Track, User, etc.) that client code will interact with.
- Models: Both Public models (in Sources/ScrobbleKit/Public/Models) and Internal models (inside Internal/Models). These represent the structured data exchanged with the Last.fm API (like SBKAlbum, SBKArtist, SBKTrack, etc.).
- Helper & Extensions: Utility classes and extensions (for URL building, error handling, etc.) are located under Sources/ScrobbleKit/Helpers and Sources/ScrobbleKit/Extensions. They play key roles in formatting parameters, handling networking errors, and converting data types.
- Error Handling: Distributed throughout under both Helpers/Error and within related service directories. This modularization ensures that API errors and scrobble-specific errors are captured and conveyed properly.

##### Relationships and Data Flow
- The client initializes a SBKManager instance using API credentials. This manager acts as the orchestrator.
- From the manager, client calls (e.g., getInfo(forAlbum:) or startSession(username:password:)) are forwarded to the Public Methods layer.
- The Public Methods layer delegates execution to corresponding Internal Services. For example, when fetching album info, the Album service under Internal/Services/Methods/Album is invoked.
- Internal Services then handle the detailed network interactions and use helper utilities, such as SBKURLBuilder for constructing API endpoints.
- Responses are parsed into structured Models (both Public and Internal) after being processed by decoder utilities like NumericStringDecoder.
- Error handling is centralized via the Error Helpers classes, ensuring clients receive meaningful error feedback.

##### Architectural Patterns and Design Principles
- Layered Architecture: The project is clearly organized into layers (Public API, Internal Services, Helpers, Models). This separation encourages maintainability and extensibility.
- Modular Design: Each API method (e.g., Album, Artist, User, Track, etc.) is segregated into its own directory tree. This modularity allows for scaling the library by adding or modifying modules without affecting other areas.
- Use of Async/Await: The asynchronous nature is a core design decision, which should be represented as network calls flowing asynchronously from SBKManager through Internal Services.
- Extension-based Enhancements: The Extensions directory demonstrates how the library leverages Swift extensions to add utility methods to standard types (e.g., String, URLQueryItem).

b. Within the Public API section, include blocks for each method group (Album, Artist, Chart, Geo, Track, User, etc.) alongside a dedicated block for models (data structures).
c. In the Internal Implementation section, further divide into:
- Internal Services (grouped by method types),
- Helpers/Extensions,
- Error Handling Utilities.
e. An external block labeled “Last.fm API” and connect it to the Internal Services blocks to illustrate outgoing network requests.

– Clearly defined boundaries between Public API (client-facing) and Internal modules.
– Separation of concerns (each API method type in its dedicated module).
– Explicit data flow from SBKManager through helper utilities to the Last.fm API.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level entry point
    SBKManager["SBKManager"]:::manager

    %% ScrobbleKit Library Container
    subgraph "ScrobbleKit Library"
        %% Public API Section
        subgraph "Public API"
            PublicAPI_Methods["Public API Methods"]:::public
            Public_Models["Public Models"]:::models
        end

        %% Internal Implementation Section
        subgraph "Internal Implementation"
            Internal_Services["Internal Services"]:::internal
            Internal_Models["Internal Models"]:::models
            HelperUtilities["Helper Utilities"]:::helper
            Extensions["Extensions"]:::helper
            Error_Handling["Error Handling"]:::error
            Auth_Service["Authentication Service"]:::internal
        end
    end

    %% External Last.fm API
    External["Last.fm API"]:::external

    %% Connections
    SBKManager -->|"calls"| PublicAPI_Methods
    PublicAPI_Methods -->|"delegates"| Internal_Services
    SBKManager -->|"startSession"| Auth_Service

    Internal_Services -->|"async/await"| External
    Internal_Services -->|"buildsURL"| HelperUtilities
    Internal_Services -->|"buildsURL"| Extensions
    Internal_Services -->|"parsing"| Internal_Models
    Internal_Models -->|"exposedTo"| Public_Models
    Internal_Services -->|"error"| Error_Handling
    Error_Handling -->|"propagates"| SBKManager

    %% Click Events
    click SBKManager "https://github.com/tfmart/scrobblekit/blob/main/Sources/ScrobbleKit/SBKManager.swift"
    click PublicAPI_Methods "https://github.com/tfmart/scrobblekit/tree/main/Sources/ScrobbleKit/Public"
    click Public_Models "https://github.com/tfmart/scrobblekit/tree/main/Sources/ScrobbleKit/Public/Models"
    click Internal_Services "https://github.com/tfmart/scrobblekit/tree/main/Sources/ScrobbleKit/Internal/Services"
    click Internal_Models "https://github.com/tfmart/scrobblekit/tree/main/Sources/ScrobbleKit/Internal/Models"
    click HelperUtilities "https://github.com/tfmart/scrobblekit/tree/main/Sources/ScrobbleKit/Helpers"
    click Extensions "https://github.com/tfmart/scrobblekit/tree/main/Sources/ScrobbleKit/Extensions"
    click Error_Handling "https://github.com/tfmart/scrobblekit/tree/main/Sources/ScrobbleKit/Helpers/Error"
    click Auth_Service "https://github.com/tfmart/scrobblekit/blob/main/Sources/ScrobbleKit/Internal/Services/Methods/Auth/AuthSessionService.swift"

    %% Styles
    classDef manager fill:#ADD8E6,stroke:#000,stroke-width:2px
    classDef public fill:#90EE90,stroke:#000,stroke-width:2px
    classDef internal fill:#FFA07A,stroke:#000,stroke-width:2px
    classDef models fill:#FFD700,stroke:#000,stroke-width:2px
    classDef helper fill:#DA70D6,stroke:#000,stroke-width:2px
    classDef error fill:#FF6347,stroke:#000,stroke-width:2px
    classDef external fill:#F08080,stroke:#000,stroke-width:2px
```
