diff --git a/lib/blocs/balance/balance_bloc.dart b/lib/blocs/balance/balance_bloc.dart
index 9d7672c..aed6934 100644
--- a/lib/blocs/balance/balance_bloc.dart
+++ b/lib/blocs/balance/balance_bloc.dart
@@ -1,3 +1,36 @@
+/// A BLoC (Business Logic Component) that manages balance-related operations for groups.
+///
+/// This bloc handles the calculation and management of user balances within groups,
+/// including optimal settlement calculations and marking settlements as completed.
+///
+/// The bloc processes three main events:
+/// - [LoadGroupBalances]: Loads and calculates all user balances for a specific group
+/// - [RefreshBalance]: Refreshes the balance data while maintaining the current state when possible
+/// - [MarkSettlementAsCompleted]: Records a settlement transaction between users
+///
+/// Dependencies:
+/// - [BalanceRepository]: Repository for balance data operations
+/// - [BalanceService]: Service for balance calculations and settlement logic
+/// - [ErrorService]: Service for error logging and handling
+///
+/// Example usage:
+/// ```dart
+/// final balanceBloc = BalanceBloc(
+///   balanceRepository: balanceRepository,
+///   expenseRepository: expenseRepository,
+/// );
+/// 
+/// // Load balances for a group
+/// balanceBloc.add(LoadGroupBalances('groupId123'));
+/// 
+/// // Mark a settlement as completed
+/// balanceBloc.add(MarkSettlementAsCompleted(
+///   groupId: 'groupId123',
+///   fromUserId: 'user1',
+///   toUserId: 'user2',
+///   amount: 50.0,
+/// ));
+/// ```
 import 'package:flutter_bloc/flutter_bloc.dart';
 import '../../repositories/balance_repository.dart';
 import '../../repositories/expense_repository.dart';
diff --git a/lib/services/balance_service.dart b/lib/services/balance_service.dart
index eb65978..278576a 100644
--- a/lib/services/balance_service.dart
+++ b/lib/services/balance_service.dart
@@ -1,3 +1,36 @@
+/// Service responsible for calculating and managing financial balances within travel groups.
+///
+/// This service handles:
+/// - Group balance calculations
+/// - Individual user balance tracking
+/// - Optimal settlement calculations (debt optimization)
+/// - Real-time balance streaming
+/// - Group spending statistics and analytics
+///
+/// The service uses a greedy algorithm to optimize settlements between users,
+/// minimizing the number of transactions needed to settle all debts.
+///
+/// Example usage:
+/// ```dart
+/// final balanceService = BalanceService(
+///   balanceRepository: balanceRepository,
+///   expenseRepository: expenseRepository,
+/// );
+///
+/// // Get real-time balance updates
+/// balanceService.getGroupBalanceStream(groupId).listen((balance) {
+///   print('Total expenses: ${balance.totalExpenses}');
+///   print('Settlements needed: ${balance.settlements.length}');
+/// });
+///
+/// // Calculate optimal settlements
+/// final settlements = await balanceService.calculateOptimalSettlements(groupId);
+/// ```
+///
+/// See also:
+/// - [GroupBalance] for the complete balance structure
+/// - [Settlement] for individual payment recommendations
+/// - [UserBalance] for per-user balance information
 import '../models/group_balance.dart';
 import '../models/expense.dart';
 import '../models/group_statistics.dart';