# System Architecture

## Project Structure

### Core Directory (`lib/core/`)
Central infrastructure and shared components:
- **Dependency Injection**: GetIt-based service locator in `locator_service.dart`
- **Routing**: GoRouter implementation in `app_router.dart` with deep linking
- **Theme**: Material theme with Mulish font family in `theme/theme_helper.dart`
- **Networking**: Dio HTTP client with token interceptor
- **WebSockets**: Pusher Channels for real-time communication
- **State Management**: Flutter BLoC/Cubit pattern

### Features Directory (`lib/features/`)
Feature-based modular architecture with 35+ feature modules:

**Core Features:**
- `auth/` - Authentication (email/password, OAuth)
- `feed/` - Content discovery feed
- `diary/` - Food diary tracking
- `chat/` - Real-time messaging
- `consultations/` - Consultation management
- `profile/` - User profiles and settings

**Content Creation:**
- `create_recipe/` - Recipe creation
- `create_diet/` - Diet plan creation
- `create_plan/` - Nutrition plan creation
- `blog_post_create/` - Blog post creation

**User Management:**
- `settings/` - User preferences
- `user_details/` - User information management
- `menu/` - App navigation menu
- `bottom_navigation_bar/` - Main navigation

**Consultant Features:**
- `consultant/` - Consultant verification
- `consultant_rating/` - Rating system
- `finances_and_consultations_archive/` - Financial tracking

**Supporting Features:**
- `notifications/` - Push notifications
- `glossary/` - Nutrition glossary
- `calendar/` - Calendar integration
- `support/` - Customer support
- `welcome/` - Onboarding
- `update_screen/` - App update management

## Architectural Patterns

### Clean Architecture Layers

Each feature follows a layered structure:

```
feature/
├── models/          # Data models (freezed + json_serializable)
├── services/        # API services (Retrofit)
├── repositories/    # Data repositories
├── presentation/    # UI layer
│   ├── pages/       # Screen widgets
│   ├── widgets/     # Feature-specific widgets
│   └── bloc/        # State management (Cubit)
└── entities/        # Domain entities
```

### Dependency Injection

**Registration Structure** (`lib/core/di/`):
- `app_config_registration.dart` - App configuration
- `external_registrations.dart` - External dependencies (Dio, etc.)
- `service_registrations.dart` - API services
- `repository_registrations.dart` - Data repositories
- `cubit_registrations.dart` - State management

**Service Lifecycle:**
- Singleton: Services, Repositories (most common)
- Factory: Cubits that need fresh instances
- Lazy Singleton: WebSocket manager, core services

### State Management Pattern

**BLoC/Cubit Implementation:**
- Global state: Registered in `AppConfig.globalBlocProviders`
- Feature state: Created per screen/feature
- State classes: Freezed unions for type-safe states

**Global Cubits:**
- `NewMessagesCubit` - Message notifications
- `NotificationsCubit` - Push notifications
- `FeedCubit` - Feed content
- `ProfileAvatarCubit` - User profile
- `ChatsCubit` - Chat rooms
- `ViewsCubit` - Content view tracking
- `InternetConnectionCubit` - Network status

## Data Flow

### API Integration

**Base Setup:**
- Base URL: Configurable via environment (prod/dev)
- HTTP Client: Dio with interceptors
- API Services: Retrofit for type-safe endpoints
- Authentication: Bearer token in headers

**Interceptors:**
1. `TokenInterceptor` - Adds auth token, handles 401 errors
2. `PhoneVerifyErrorInterceptor` - Handles phone verification errors

### Real-time Communication

**WebSocket Architecture:**
- Library: `dart_pusher_channels`
- Manager: `WsManager` (singleton)
- Connection: Authenticated via backend endpoint

**Channels:**
1. Private Notifications: `App\Events\BroadcastNotificationCreated`
2. Private Messages: `App\Events\ChatMessageUpdated`
3. Direct Chat: Room-specific message updates
4. Client Typing: Real-time typing indicators

**Socket ID Storage:**
- Persisted via SharedPreferences
- Used for authentication and channel subscription

### Authentication Flow

**Methods:**
1. Email/Password - Traditional credentials
2. OAuth Providers:
   - VK ID (Russian social network)
   - Yandex ID
   - OK (Odnoklassniki)
   - Mail.ru

**Token Management:**
- Storage: SharedPreferences via `TokenStorage`
- Refresh: Automatic on 401 response
- Logout: Token removal + WebSocket cleanup

**Post-Authentication:**
1. WebSocket initialization
2. Profile loading
3. Chat room loading
4. Notification loading
5. Firebase push token registration

## Navigation Architecture

### GoRouter Setup

**Route Structure:**
- Shell routes for persistent bottom navigation
- Named routes for easy navigation
- Deep linking support for content (recipe/blog_post/plan/diet)

**Route Groups:**
- `AuthRoutes` - Login, registration, password reset
- `MainNavigationRoutes` - Shell route with bottom nav
- `ContentRoutes` - Content viewing screens
- `SettingsRoutes` - User settings
- `OtherRoutes` - Miscellaneous screens

**Deep Linking Pattern:**
```
/content/{type}/{identifier}
- /content/recipe/{slug}
- /content/blog_post/{id}
- /content/plan/{slug}
- /content/diet/{slug}
```

### Bottom Navigation

**Main Sections:**
1. My Profile - User profile and content
2. Feed - Content discovery
3. Diary - Food tracking
4. Consultations - Consultation management
5. Chat - Messaging
6. Notifications - Notification center
7. Menu - Settings and more

**Implementation:**
- `BottomNavigationBarWidget` wraps content
- No transition animations for tab switches
- WebSocket initialization on feed screen

## Data Persistence

### Storage Solutions

**SharedPreferences:**
- Authentication token
- Socket ID
- User preferences

**Cached Network Images:**
- Library: `cached_network_image`
- Automatic caching of user avatars, content images

**Firebase:**
- Push notification tokens
- Remote configuration
- Analytics events

## Critical Implementation Details

### Content View Tracking

**Pattern:**
- `ViewsCubit` handles visibility detection
- `VisibilityDetector` widget tracks on-screen time
- Views sent to backend when 50%+ visible for 2+ seconds
- Debounced to prevent excessive API calls

**Tracked Content:**
- Blog posts
- Recipes
- Diets
- Nutrition plans

### Image Handling

**Upload Flow:**
1. `ImagePicker` for selection
2. `FlutterImageCompress` for compression
3. MultiPart form data upload via Dio
4. Preview via `CachedNetworkImage`

**Supported Formats:**
- User photos (profile, diary)
- Content images (recipes, diets, plans)
- Chat attachments

### Search Implementation

**Debounced Search:**
- Library: `easy_debounce`
- Delay: 500ms
- Min query length: 3 characters
- Applied to: Feed, Recipes, Diets, Plans, Consultants

**Tag-based Filtering:**
- Recipe tags for filtering
- Modal bottom sheet UI
- Persistent selection across sessions

### Pagination Pattern

**Implementation:**
- Page-based pagination
- Scroll detection for next page load
- Loading state during fetch
- Meta data tracking (current page, last page)

**Example (FeedCubit):**
```dart
currentPage = 1
lastPage = meta.lastPage
loadNextPage() when currentPage < lastPage
```

## Error Handling

### Network Errors

**401 Unauthorized:**
- Auto logout
- Token removal
- Navigate to auth screen

**Connection Errors:**
- `InternetConnectionCubit` monitors status
- Retry mechanisms in repositories
- User-friendly error messages

### State Error Handling

**Pattern:**
```dart
sealed class State {
  const State.loading();
  const State.loaded({required data});
  const State.error({required String errorMessage});
}
```

**UI Response:**
- Loading: Show loaders/skeletons
- Error: Show `DataErrorWidget` with retry
- Empty: Show empty state messages

## Performance Optimizations

### Lazy Loading
- Lazy singleton services
- On-demand cubit creation
- Deferred widget loading

### Image Optimization
- Compression before upload
- Cached network images
- Thumbnail generation

### WebSocket Management
- Connection reuse
- Automatic reconnection
- Proper cleanup on logout

### List Rendering
- Pagination for large lists
- ListView.builder for efficiency
- Visibility detection for tracking

## Platform-Specific Features

### Android
- Huawei HMS support for Huawei devices
- Google FCM for push notifications
- ProGuard rules for release builds
- QR code scanning via camera

### iOS
- APNs for push notifications
- Deep linking configuration
- App Store compliance

### Firebase Integration
- Separate configs for Android/iOS
- Environment-based configuration
- Push notification handling
- Analytics tracking

## Security Considerations

### Authentication
- Bearer token authentication
- Secure token storage
- Automatic session management
- OAuth 2.0 for social login

### Data Protection
- HTTPS only communication
- Token encryption in storage
- Secure WebSocket connections
- Privacy policy compliance

## Key Files Reference

**Entry Point:**
- `lib/main.dart` - App initialization

**Core Infrastructure:**
- `lib/core/app_initializer.dart` - Startup sequence
- `lib/core/locator_service.dart` - DI container
- `lib/core/app_config.dart` - App configuration
- `lib/core/app_router.dart` - Routing setup

**WebSocket:**
- `lib/core/websockets/ws_manager.dart` - Connection management
- `lib/core/websockets/ws_service.dart` - API service

**Authentication:**
- `lib/features/auth/sdk/social_auth_facade.dart` - Social auth
- `lib/core/token_storage.dart` - Token persistence
- `lib/core/interceptors/token_interceptor.dart` - Auth interceptor

**Environment:**
- `lib/core/env_config.dart` - Environment variables
- `.env` - Environment file (not in repo)