eatvio_app/.kilocode/rules/memory-bank/architecture.md

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):

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:

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)