# WalkGuide Design Pattern Documentation

## Builder - Creational
- Backend DTO/entity builders via Lombok `@Builder`.
- Files: `PairingStatusResponse.java`, `AgoraTokenResponse.java`, entity classes such as `PairingRelation.java`.
- Reason: response/entity construction has many optional fields, so builder calls are clearer than long constructors.

## Singleton / Service Locator - Creational
- Flutter registers app-wide services once with GetIt.
- File: `walkguide-mobile/walkguide_app/lib/app/injection_container.dart`.
- Examples: `TtsService`, `WebSocketService`, `CallService`, `YoloDetector`.
- Reason: resource-heavy services need one shared lifecycle.

## Facade - Structural
- Flutter service classes hide low-level plugins from UI.
- Files: `TtsService`, `HapticService`, `FcmService`, `CallService`, `WebSocketService`.
- Reason: screens call simple domain-oriented methods instead of plugin APIs directly.

## Repository - Structural
- Backend repositories abstract JPA persistence.
- Files: `UserRepository`, `PairingRelationRepository`, `LocationHistoryRepository`, etc.
- Reason: service layer works against repository contracts, not SQL.

## Observer - Behavioral
- Flutter BLoC/Cubit and ChangeNotifier notify screens on state changes.
- Backend WebSocket broker pushes location/SOS/notification updates to subscribers.
- Files: `AppCubit`, `WebSocketService`, `LocationBroadcaster`.
- Reason: real-time features need push updates without polling.

## Strategy - Behavioral
- Obstacle direction/distance analysis can vary independently from camera capture.
- File: `core/ai/obstacle_analyzer.dart`.
- Reason: detection interpretation is isolated so thresholds/rules can evolve.

## Chain of Responsibility - Behavioral
- Dio interceptors handle token injection, refresh, and error flow.
- File: `core/network/api_client.dart`.
- Reason: each request passes through consistent auth/error handling before reaching UI.