# Mobile Application Architecture

This document provides a comprehensive overview of the design architecture, state management, and structural breakdown of the SmartBulls mobile application.

---

## 1. Application Framework and Patterns

The mobile client is built using **Flutter (SDK ^3.5.4)** and follows a structured Model-View-ViewModel/Provider pattern for reactive state management.

```mermaid
graph TD
    UI[Widgets / Screens]
    Providers[Provider State classes]
    HttpService[Custom HTTP Helper]
    SocketService[Websocket Ticker Channels]
    API[Node.js API Server]
    
    UI -->|Read / Watch| Providers
    UI -->|User Inputs| Providers
    Providers -->|Trigger HTTP| HttpService
    Providers -->|Listen to ticks| SocketService
    
    HttpService -->|REST calls| API
    SocketService -->|Quotes Stream| API
```

---

## 2. State Management (Provider Pattern)

The app leverages the `provider` library to manage app-wide state and propagate updates to the widget tree:

* **AuthProvider:** Manages user authentication, registers device tokens, handles logins, updates PIN verification state, and cleans session context on logout or account deletion.
* **DataProvider:** Manages static configuration, metadata, indices list, watchlist tokens, and other common elements.
* **ContestProvider:** Manages active, upcoming, and past contest structures, handles contest join logic, and tracks rewards.
* **MarketSocketProvider / WebSocketProvider:** Listens to the background websocket quote tick feeds (Equity, F&O, Crypto) and triggers reactive updates of LTP changes to the UI.

---

## 3. Directory Structure

```
Smartbulls_app/
├── android/                 # Android-native configuration files
├── ios/                     # iOS-native configuration files
├── assets/                  # Images, icons, JSON templates, and Lottie animations
├── lib/
│   ├── api/                 # Network communication files
│   │   ├── http.dart        # Custom HTTP client wrapper
│   │   ├── rest_api.dart    # Endpoint declarations and base host configurations
│   │   └── failure.dart     # Custom failure structures
│   ├── model/               # Data model serialization classes
│   ├── provider/            # Reactive state management classes
│   ├── screens/             # UI views grouped by feature modules
│   │   ├── auth/            # Register, Login, Verification, and Forgot PIN screens
│   │   ├── home/            # Dashboard, top-up, and plan displays
│   │   ├── contests/        # Contests, portfolios, and rankings displays
│   │   └── account/         # User profile, history, settings, and support forms
│   ├── util/                # Common helper keys, logs, formatting rules, and alerts
│   └── main.dart            # Flutter application entry point
├── pubspec.yaml             # Third-party packages and asset declarations
└── pubspec.lock             # Exact resolved package versions
```