# sudeep-ps/chatbond architecture

> Architecture diagram of the GitHub repository sudeep-ps/chatbond, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sudeep-ps/chatbond
- Repository: https://github.com/sudeep-ps/chatbond

## Overview

#### Purpose and entry points
ChatBond is a cross-platform Flutter chat application with authentication, chat, profile/media, and settings flows. Flutter starts at `lib/main.dart`; application navigation and visual configuration are centralized in `lib/config/router.dart` and `lib/config/theme.dart`. Native hosts package the same Dart application for Android, iOS, desktop, and web, e.g. `android/app/src/main/kotlin/com/example/chatbond/MainActivity.kt` and `ios/Runner/AppDelegate.swift`.

#### Application composition
The app is organized by feature with a Clean Architecture-style separation:
- Presentation: pages, widgets, and state providers.
- Domain: entities, repository contracts, and use cases.
- Data: remote/local data sources and repository implementations.

This boundary is consistently represented by `lib/features/auth/`, `lib/features/chat/`, and `lib/features/profile/`. UI providers should invoke domain use cases/contracts rather than directly own transport or persistence details.

#### Authentication lifecycle
Authentication includes login, registration, forgot/reset-password, and OTP verification screens. The presentation state controller is `lib/features/auth/presentation/providers/auth_provider.dart`; user and OTP response models live in `lib/features/auth/domain/entities/auth_user.dart` and `lib/features/auth/domain/entities/verify_otp_response.dart`. Requests flow through `lib/features/auth/data/datasources/auth_remote_data_source_impl.dart` and `lib/features/auth/data/repositories/auth_repository_impl.dart`, behind the contract at `lib/features/auth/domain/repositories/auth_repository.dart`.

#### Chat and realtime flow
Chat is the primary interactive feature. `lib/features/chat/presentation/pages/chat_page.dart` renders conversations using state from `lib/features/chat/presentation/providers/chat_provider.dart`. Provider actions pass through chat use cases/repository boundaries to `lib/features/chat/data/datasources/chat_remote_data_source_impl.dart`. Domain models in `lib/features/chat/domain/entities/chat.dart` and `lib/features/chat/domain/entities/message.dart` define the shared business representation. Realtime socket connectivity is isolated in `lib/core/websocket/socket_service.dart`, separating event transport from chat UI and repository logic.

#### Profile and media pipeline
Profile UI and settings are rooted at `lib/features/profile/presentation/pages/profile_page.dart` and managed by `lib/features/profile/presentation/providers/profile_provider.dart`. Media selection/local handling is abstracted through `lib/features/profile/data/datasources/media_local_data_source_impl.dart`; remote asset upload/storage is separately abstracted in `lib/features/profile/data/datasources/storage_remote_data_source_impl.dart`. Corresponding repository contracts keep device-media and remote-storage concerns distinct.

#### Shared infrastructure and persistence
`lib/core/network/api_client.dart` is the common HTTP/API boundary used by remote data sources. Authentication/session persistence is isolated in `lib/core/storage/auth_session.dart` and `lib/core/storage/token_storage.dart`, allowing authenticated API behavior to be decoupled from feature screens. Shared exception types and Firebase helpers reside in `lib/core/exceptions/exceptions.dart` and `lib/core/utils/firebase_utils.dart`.

#### External platforms and services
The runtime is Flutter/Dart, targeting Android, iOS, web, Linux, macOS, and Windows. Firebase is configured via `lib/firebase_options.dart` with project deployment/configuration in `firebase.json`; Firebase utilities indicate Firebase-backed app capabilities. The app also depends on an external HTTP backend and a socket/WebSocket service, represented by the API client and socket boundary. Platform launch/build integration remains in the generated native projects, notably `android/`, `ios/`, `web/`, `linux/`, `macos/`, and `windows/`.

Main entry points: [`lib/core/network/api_client.dart`](https://github.com/sudeep-ps/chatbond/blob/main/lib/core/network/api_client.dart) (API client), [`lib/config/router.dart`](https://github.com/sudeep-ps/chatbond/blob/main/lib/config/router.dart) (Router & theme), [`lib/features/auth/presentation/providers/auth_provider.dart`](https://github.com/sudeep-ps/chatbond/blob/main/lib/features/auth/presentation/providers/auth_provider.dart) (Auth UI state), [`lib/features/chat/presentation/providers/chat_provider.dart`](https://github.com/sudeep-ps/chatbond/blob/main/lib/features/chat/presentation/providers/chat_provider.dart) (Chat state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_flutter_entry["Flutter entry<br/>Dart bootstrap<br/>[main.dart]"]
  node_app_config["Router &amp; theme<br/>app configuration<br/>[router.dart]"]
  node_native_hosts["Native and web hosts<br/>platform runtimes<br/>[MainActivity.kt]"]
end

subgraph group_auth["Authentication"]
  node_auth_ui_state["Auth UI state<br/>presentation provider<br/>[auth_provider.dart]"]
  node_auth_domain["Auth contract &amp; models<br/>domain boundary"]
  node_auth_remote["Auth repository &amp; remote<br/>data layer"]
end

subgraph group_chat["Chat"]
  node_chat_ui["Chat page<br/>presentation page<br/>[chat_page.dart]"]
  node_chat_state["Chat state<br/>presentation provider<br/>[chat_provider.dart]"]
  node_chat_domain["Chat domain<br/>entities and repository boundary<br/>[chat.dart]"]
  node_chat_remote["Chat remote source<br/>data source"]
end

subgraph group_profile["Profile &amp; media"]
  node_profile_ui_state["Profile UI state<br/>page and provider<br/>[profile_page.dart]"]
  node_media_local["Local media source<br/>device media data source"]
  node_storage_remote["Remote storage source<br/>asset storage data source"]
end

subgraph group_core["Core infrastructure"]
  node_api_client["API client<br/>HTTP boundary<br/>[api_client.dart]"]
  node_session_storage[("Session &amp; token storage<br/>authenticated persistence<br/>[auth_session.dart]")]
  node_socket_service["Socket service<br/>realtime transport"]
  node_firebase{{"Firebase integration<br/>backend platform configuration"}}
end

node_external_backend{{"HTTP backend<br/>external service"}}
node_socket_backend{{"WebSocket service<br/>external realtime service"}}

node_native_hosts -->|"launches"| node_flutter_entry
node_flutter_entry -->|"initializes"| node_app_config
node_app_config -->|"routes to"| node_auth_ui_state
node_app_config -->|"routes to"| node_chat_ui
node_app_config -->|"routes to"| node_profile_ui_state
node_chat_ui -->|"renders state from"| node_chat_state
node_auth_ui_state -->|"uses contract"| node_auth_domain
node_auth_domain -->|"implemented by"| node_auth_remote
node_auth_remote -->|"requests through"| node_api_client
node_auth_ui_state -->|"persists session"| node_session_storage
node_chat_state -->|"uses domain boundary"| node_chat_domain
node_chat_domain -->|"loads via"| node_chat_remote
node_chat_remote -->|"requests through"| node_api_client
node_chat_state -->|"realtime events"| node_socket_service
node_profile_ui_state -->|"selects media via"| node_media_local
node_profile_ui_state -->|"uploads assets via"| node_storage_remote
node_storage_remote -->|"uses API boundary"| node_api_client
node_api_client -->|"uses auth token"| node_session_storage
node_api_client -->|"HTTP requests"| node_external_backend
node_socket_service -->|"socket connection"| node_socket_backend
node_firebase -.->|"Firebase-backed capabilities"| node_external_backend

click node_flutter_entry "https://github.com/sudeep-ps/chatbond/blob/main/lib/main.dart"
click node_app_config "https://github.com/sudeep-ps/chatbond/blob/main/lib/config/router.dart"
click node_native_hosts "https://github.com/sudeep-ps/chatbond/blob/main/android/app/src/main/kotlin/com/example/chatbond/MainActivity.kt"
click node_auth_ui_state "https://github.com/sudeep-ps/chatbond/blob/main/lib/features/auth/presentation/providers/auth_provider.dart"
click node_auth_domain "https://github.com/sudeep-ps/chatbond/blob/main/lib/features/auth/domain/repositories/auth_repository.dart"
click node_auth_remote "https://github.com/sudeep-ps/chatbond/blob/main/lib/features/auth/data/repositories/auth_repository_impl.dart"
click node_chat_ui "https://github.com/sudeep-ps/chatbond/blob/main/lib/features/chat/presentation/pages/chat_page.dart"
click node_chat_state "https://github.com/sudeep-ps/chatbond/blob/main/lib/features/chat/presentation/providers/chat_provider.dart"
click node_chat_domain "https://github.com/sudeep-ps/chatbond/blob/main/lib/features/chat/domain/entities/chat.dart"
click node_chat_remote "https://github.com/sudeep-ps/chatbond/blob/main/lib/features/chat/data/datasources/chat_remote_data_source_impl.dart"
click node_profile_ui_state "https://github.com/sudeep-ps/chatbond/blob/main/lib/features/profile/presentation/pages/profile_page.dart"
click node_media_local "https://github.com/sudeep-ps/chatbond/blob/main/lib/features/profile/data/datasources/media_local_data_source_impl.dart"
click node_storage_remote "https://github.com/sudeep-ps/chatbond/blob/main/lib/features/profile/data/datasources/storage_remote_data_source_impl.dart"
click node_api_client "https://github.com/sudeep-ps/chatbond/blob/main/lib/core/network/api_client.dart"
click node_session_storage "https://github.com/sudeep-ps/chatbond/blob/main/lib/core/storage/auth_session.dart"
click node_socket_service "https://github.com/sudeep-ps/chatbond/blob/main/lib/core/websocket/socket_service.dart"
click node_firebase "https://github.com/sudeep-ps/chatbond/blob/main/lib/firebase_options.dart"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flutter_entry,node_app_config,node_native_hosts toneBlue
class node_auth_ui_state,node_auth_domain,node_auth_remote toneAmber
class node_chat_ui,node_chat_state,node_chat_domain,node_chat_remote toneMint
class node_profile_ui_state,node_media_local,node_storage_remote toneRose
class node_api_client,node_session_storage,node_socket_service,node_firebase toneIndigo
class node_external_backend,node_socket_backend toneNeutral
```

## Components

### App shell

- [Flutter entry](https://github.com/sudeep-ps/chatbond/blob/main/lib/main.dart): Dart bootstrap · `lib/main.dart`
- [Router & theme](https://github.com/sudeep-ps/chatbond/blob/main/lib/config/router.dart): app configuration · `lib/config/router.dart`
- [Native and web hosts](https://github.com/sudeep-ps/chatbond/blob/main/android/app/src/main/kotlin/com/example/chatbond/MainActivity.kt): platform runtimes · Packages the shared Flutter application for supported platforms. · `android/app/src/main/kotlin/com/example/chatbond/MainActivity.kt`

### Authentication

- [Auth UI state](https://github.com/sudeep-ps/chatbond/blob/main/lib/features/auth/presentation/providers/auth_provider.dart): presentation provider · `lib/features/auth/presentation/providers/auth_provider.dart`
- [Auth contract & models](https://github.com/sudeep-ps/chatbond/blob/main/lib/features/auth/domain/repositories/auth_repository.dart): domain boundary · `lib/features/auth/domain/repositories/auth_repository.dart`
- [Auth repository & remote](https://github.com/sudeep-ps/chatbond/blob/main/lib/features/auth/data/repositories/auth_repository_impl.dart): data layer · `lib/features/auth/data/repositories/auth_repository_impl.dart`

### Chat

- [Chat page](https://github.com/sudeep-ps/chatbond/blob/main/lib/features/chat/presentation/pages/chat_page.dart): presentation page · `lib/features/chat/presentation/pages/chat_page.dart`
- [Chat state](https://github.com/sudeep-ps/chatbond/blob/main/lib/features/chat/presentation/providers/chat_provider.dart): presentation provider · `lib/features/chat/presentation/providers/chat_provider.dart`
- [Chat domain](https://github.com/sudeep-ps/chatbond/blob/main/lib/features/chat/domain/entities/chat.dart): entities and repository boundary · `lib/features/chat/domain/entities/chat.dart`
- [Chat remote source](https://github.com/sudeep-ps/chatbond/blob/main/lib/features/chat/data/datasources/chat_remote_data_source_impl.dart): data source · `lib/features/chat/data/datasources/chat_remote_data_source_impl.dart`

### Profile & media

- [Profile UI state](https://github.com/sudeep-ps/chatbond/blob/main/lib/features/profile/presentation/pages/profile_page.dart): page and provider · `lib/features/profile/presentation/pages/profile_page.dart`
- [Local media source](https://github.com/sudeep-ps/chatbond/blob/main/lib/features/profile/data/datasources/media_local_data_source_impl.dart): device media data source · `lib/features/profile/data/datasources/media_local_data_source_impl.dart`
- [Remote storage source](https://github.com/sudeep-ps/chatbond/blob/main/lib/features/profile/data/datasources/storage_remote_data_source_impl.dart): asset storage data source · `lib/features/profile/data/datasources/storage_remote_data_source_impl.dart`

### Core infrastructure

- [API client](https://github.com/sudeep-ps/chatbond/blob/main/lib/core/network/api_client.dart): HTTP boundary · `lib/core/network/api_client.dart`
- [Session & token storage](https://github.com/sudeep-ps/chatbond/blob/main/lib/core/storage/auth_session.dart): authenticated persistence · `lib/core/storage/auth_session.dart`
- [Socket service](https://github.com/sudeep-ps/chatbond/blob/main/lib/core/websocket/socket_service.dart): realtime transport · `lib/core/websocket/socket_service.dart`
- [Firebase integration](https://github.com/sudeep-ps/chatbond/blob/main/lib/firebase_options.dart): backend platform configuration · `lib/firebase_options.dart`

### Other components

- **HTTP backend**: external service
- **WebSocket service**: external realtime service

## Connections

- Native and web hosts → Flutter entry: launches
- Flutter entry → Router & theme: initializes
- Router & theme → Auth UI state: routes to
- Router & theme → Chat page: routes to
- Router & theme → Profile UI state: routes to
- Chat page → Chat state: renders state from
- Auth UI state → Auth contract & models: uses contract
- Auth contract & models → Auth repository & remote: implemented by
- Auth repository & remote → API client: requests through
- Auth UI state → Session & token storage: persists session
- Chat state → Chat domain: uses domain boundary
- Chat domain → Chat remote source: loads via
- Chat remote source → API client: requests through
- Chat state → Socket service: realtime events
- Profile UI state → Local media source: selects media via
- Profile UI state → Remote storage source: uploads assets via
- Remote storage source → API client: uses API boundary
- API client → Session & token storage: uses auth token
- API client → HTTP backend: HTTP requests
- Socket service → WebSocket service: socket connection
- Firebase integration → HTTP backend: Firebase-backed capabilities