How tfmart/scrobblekit works
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.