A repository is a core part of the data layer. Its main responsibility is to manage application data of a specific type. Think of it as the one trusted place in your app where that particular data lives and gets updated. This makes the repository the source of truth for that data.

Repositories do more than just store data. They handle tasks like fetching new data from APIs, retrying failed requests, managing cached versions of the data, and converting raw responses into structured models your app can actually use.

In most real-world apps, you should have a separate repository for each major type of data. For example, the Compass app uses dedicated repositories like UserRepository, AuthRepository, BookingRepository, and DestinationRepository—each with its own role.

Here’s a simplified version of the BookingRepositoryRemote used in Compass:

class BookingRepositoryRemote implements BookingRepository {
  BookingRepositoryRemote({
    required ApiClient apiClient,
  }) : _apiClient = apiClient;

  final ApiClient _apiClient;
  List<Destination>? _cachedDestinations;

  Future<Result<void>> createBooking(Booking booking) async {...}
  Future<Result<Booking>> getBooking(int id) async {...}
  Future<Result<List<BookingSummary>>> getBookingsList() async {...}
  Future<Result<void>> delete(int id) async {...}
}

In this example, the BookingRepositoryRemote class communicates with a remote server using an ApiClient. This helps the app perform actions like creating or deleting bookings or retrieving booking lists from the backend.

The key idea here is abstraction. The repository knows how to work with services like ApiClient, but it keeps that logic hidden from the UI layer. This avoids tight coupling and improves testability.

You can even have multiple versions of a repository for different environments. For instance, BookingRepositoryLocal it might be used in development, while BookingRepositoryRemote it is used in production. Both share the same interface but fetch data differently.

Lastly, keep in mind that repositories and services often have a many-to-many relationship. A repository might rely on several services to collect data, while a single service might support multiple repositories.