Project Structure

Project Structure

The code is organized in layers. Domain stuff is in the middle and doesn't depend on anything external.

How it's organized

This uses Clean Architecture (Hexagonal/Ports & Adapters). Basically, layers depend inward with clear separation.

Layer Structure

api/

The main entry point. LastFmClient is what you use.

application/

Services that handle validation and business logic. Like ArtistService - it validates inputs and calls the gateway.

domain/

The core models and interfaces. model/ has your entities (like Artist), and port/ has the interfaces that get implemented in infrastructure.

Domain stuff:

• No external dependencies
• Just models and interfaces
• Doesn't care about HTTP or API structure

infrastructure/

Where external stuff lives. gateway/ implements the domain interfaces. Each domain (artist, album, etc.) has:

• A gateway (like ArtistGatewayImpl)
• A mapper that converts Last.fm DTOs to domain models
• A response/ folder with DTOs matching Last.fm's JSON

DTOs match Last.fm's JSON structure. We deserialize into DTOs, then the mapper converts to domain models. This keeps domain clean.

The http/ package is the HTTP client wrapper everything uses.

Why this structure

• Test each layer independently
• Easy to swap stuff (like HTTP clients)
• Clear separation = easier to understand
• Business logic isn't tied to external stuff