# muhd-fahad/contacts-app architecture

> Architecture diagram of the GitHub repository muhd-fahad/contacts-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/muhd-fahad/contacts-app
- Repository: https://github.com/muhd-fahad/contacts-app

## Overview

##### Project type + purpose (from file tree + README)
This is a **Flutter application** (cross-platform) named “contacts”. The README is the default Flutter template, so the **file tree is the main source of architectural truth**.

From `lib/` structure, the purpose is a **local contacts manager**:
- CRUD screens: `add_contact_screen.dart`, `update_contact_screen.dart`, `detailed_screen.dart`, `home_screen.dart`
- Local persistence: `lib/db/db_helper.dart`
- State management: `lib/provider/contact_provider.dart`, `lib/provider/theme_provider.dart`
- Domain model: `lib/model/contact_model.dart`

Targets include **Android** (`android/`) and **Web** (`web/`).

##### Key directories / files
- `lib/main.dart`: App entrypoint; wires up providers, theme, routes, and initial screen.
- `lib/screens/*`: UI layer (Flutter widgets) representing user flows.
- `lib/provider/*`: State management / business orchestration (Provider pattern).
- `lib/db/db_helper.dart`: Persistence layer abstraction (likely SQLite via `sqflite` or similar).
- `lib/model/contact_model.dart`: Data model (entity + mapping to/from DB rows).
- `android/` and `web/`: Platform shells/build artifacts (important for deployment view).

This strongly suggests a **layered client-only architecture**:
UI (screens) → State/Logic (providers) → Data Access (DB helper) → Local DB (SQLite / local storage)

No backend service is evident.

##### User interacts with a Screen
2. Screen calls **ContactProvider** methods (e.g., `addContact()`, `loadContacts()`, `updateContact()`, `deleteContact()`)
##### Screen rebuilds based on provider state

- Data returning from DB → Provider → UI
- Notifications from Provider → UI (reactive rebuild)

##### Theme flow
- Any Screen → ThemeProvider (toggle/set theme)
- ThemeProvider → MaterialApp theme config (in `main.dart`)
- ThemeProvider `notifyListeners()` → UI rebuild

##### Provider-based reactive architecture
- UI is **reactive** to provider changes (`notifyListeners`)
- Providers centralize state + coordinate data access
- Screens should be mostly “dumb” views (even if some logic exists)

##### Layer separation (client-only)
- **Screens**: presentation
- **Providers**: state + orchestration
- **DBHelper**: data access layer (DAL)
- **Model**: domain/data representation

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Diagram 1: System Context
%% =========================
subgraph D1["Diagram 1 — System Context (High Level)"]
direction TB

User["User"]:::external

subgraph AndroidDevice["Android Device"]
direction TB
AndroidApp["Contacts Flutter App (Android)"]:::app
end

subgraph WebBrowser["Web Browser"]
direction TB
WebApp["Contacts Flutter App (Web)"]:::app
end

LocalDB[("SQLite DB (On-device / Local Storage)")]:::db

User -->|"uses"| AndroidApp
User -->|"uses"| WebApp

AndroidApp -->|"read/write contacts"| LocalDB
WebApp -->|"read/write contacts"| LocalDB
end

%% =====================================
%% Diagram 2: Container / Runtime View
%% =====================================
subgraph D2["Diagram 2 — Container / Runtime View (Platform-aware)"]
direction TB

subgraph AndroidRuntime["Android Runtime"]
direction TB
AndroidHost["Android Host (MainActivity)"]:::runtime
AndroidManifest["Android Manifest(s)"]:::runtime
FlutterEngineAndroid["Flutter Engine + Framework"]:::runtime
end

subgraph WebRuntime["Web Runtime"]
direction TB
Browser["Browser"]:::runtime
WebIndex["Web Entry (index.html)"]:::runtime
WebManifest["Web Manifest (PWA)"]:::runtime
FlutterEngineWeb["Flutter Web Runtime (compiled JS)"]:::runtime
end

subgraph SharedDart["Shared Dart Code (lib/)"]
direction TB
MainDart["main.dart (Composition Root)"]:::app
end

Pubspec["pubspec.yaml (Dependencies)"]:::config

AndroidHost -->|"boots"| FlutterEngineAndroid
AndroidManifest -->|"declares"| AndroidHost
FlutterEngineAndroid -->|"runs"| MainDart

Browser -->|"loads"| WebIndex
WebIndex -->|"loads"| FlutterEngineWeb
WebManifest -->|"metadata"| Browser
FlutterEngineWeb -->|"runs"| MainDart

Pubspec -->|"declares deps for"| MainDart
end

%% ==================================
%% Diagram 3: Component (Engineering)
%% ==================================
subgraph D3["Diagram 3 — Component View (UI → Providers → DB)"]
direction TB

subgraph AppBoundary["Flutter App (Dart)"]
direction TB

Main["main.dart (Routes + Theme + Providers)"]:::app

subgraph UILayer["Presentation Layer (lib/screens)"]
direction TB
HomeScreen["HomeScreen"]:::ui
AddScreen["AddContactScreen"]:::ui
DetailScreen["DetailedScreen"]:::ui
UpdateScreen["UpdateContactScreen"]:::ui

Nav["Navigation / Routing"]:::nav
end

subgraph ProviderLayer["State / Orchestration (lib/provider)"]
direction TB
ContactProvider["ContactProvider"]:::provider
ThemeProvider["ThemeProvider"]:::provider

ContactState["In-memory contacts state\n(List<ContactModel>, flags)"]:::state
ThemeState["Theme state\n(Light/Dark mode)"]:::state
end

subgraph ModelLayer["Domain Model (lib/model)"]
direction TB
ContactModel["ContactModel\n(toMap/fromMap)"]:::model
end

subgraph DataLayer["Persistence (lib/db)"]
direction TB
DBHelper["DBHelper\n(DB init + CRUD queries)"]:::dal
end

end

SQLite[("SQLite DB (local)")]:::db

%% Wiring (composition root)
Main -->|"registers providers"| ContactProvider
Main -->|"registers providers"| ThemeProvider
Main -->|"configures routes"| Nav
ThemeProvider -->|"drives theme config"| Main

%% Navigation flows
HomeScreen -->|"navigateTo(add)"| AddScreen
HomeScreen -->|"navigateTo(detail)"| DetailScreen
DetailScreen -->|"navigateTo(update)"| UpdateScreen
Nav -->|"routes to"| HomeScreen
Nav -->|"routes to"| AddScreen
Nav -->|"routes to"| DetailScreen
Nav -->|"routes to"| UpdateScreen

%% CRUD calls
HomeScreen -->|"load contacts"| ContactProvider
AddScreen -->|"add contact"| ContactProvider
UpdateScreen -->|"update contact"| ContactProvider
DetailScreen -->|"delete contact"| ContactProvider

%% Theme calls
HomeScreen -->|"toggle/set theme"| ThemeProvider
AddScreen -->|"toggle/set theme"| ThemeProvider
DetailScreen -->|"toggle/set theme"| ThemeProvider
UpdateScreen -->|"toggle/set theme"| ThemeProvider

%% Provider internal state
ContactProvider -->|"updates"| ContactState
ThemeProvider -->|"updates"| ThemeState

%% Data access
ContactProvider -->|"CRUD methods"| DBHelper
DBHelper -->|"SQL query/insert/update/delete"| SQLite
SQLite -->|"rows/results"| DBHelper

%% Mapping
DBHelper -->|"maps rows ↔ model"| ContactModel
ContactProvider -->|"uses"| ContactModel

%% Reactive UI updates
ContactProvider -->|"notifyListeners + state"| HomeScreen
ContactProvider -->|"notifyListeners + state"| DetailScreen
ContactProvider -->|"notifyListeners + state"| AddScreen
ContactProvider -->|"notifyListeners + state"| UpdateScreen

ThemeProvider -->|"notifyListeners + theme"| HomeScreen
ThemeProvider -->|"notifyListeners + theme"| AddScreen
ThemeProvider -->|"notifyListeners + theme"| DetailScreen
ThemeProvider -->|"notifyListeners + theme"| UpdateScreen

end

%% =================
%% Click Events
%% =================
click MainDart "https://github.com/muhd-fahad/contacts-app/blob/main/lib/main.dart"
click Main "https://github.com/muhd-fahad/contacts-app/blob/main/lib/main.dart"

click HomeScreen "https://github.com/muhd-fahad/contacts-app/blob/main/lib/screens/home_screen.dart"
click AddScreen "https://github.com/muhd-fahad/contacts-app/blob/main/lib/screens/add_contact_screen.dart"
click UpdateScreen "https://github.com/muhd-fahad/contacts-app/blob/main/lib/screens/update_contact_screen.dart"
click DetailScreen "https://github.com/muhd-fahad/contacts-app/blob/main/lib/screens/detailed_screen.dart"

click ContactProvider "https://github.com/muhd-fahad/contacts-app/blob/main/lib/provider/contact_provider.dart"
click ThemeProvider "https://github.com/muhd-fahad/contacts-app/blob/main/lib/provider/theme_provider.dart"

click DBHelper "https://github.com/muhd-fahad/contacts-app/blob/main/lib/db/db_helper.dart"
click ContactModel "https://github.com/muhd-fahad/contacts-app/blob/main/lib/model/contact_model.dart"

click AndroidHost "https://github.com/muhd-fahad/contacts-app/blob/main/android/app/src/main/kotlin/com/weeklytask/contacts/MainActivity.kt"
click AndroidManifest "https://github.com/muhd-fahad/contacts-app/blob/main/android/app/src/main/AndroidManifest.xml"

click WebIndex "https://github.com/muhd-fahad/contacts-app/blob/main/web/index.html"
click WebManifest "https://github.com/muhd-fahad/contacts-app/blob/main/web/manifest.json"

click Pubspec "https://github.com/muhd-fahad/contacts-app/blob/main/pubspec.yaml"

%% =================
%% Styles
%% =================
classDef external fill:#0b1320,stroke:#5bc0eb,color:#eaf4ff,stroke-width:1px
classDef platform fill:#0f1b2d,stroke:#7aa2f7,color:#eaf4ff,stroke-dasharray:6 4,stroke-width:2px
classDef runtime fill:#13233d,stroke:#a6bdfc,color:#eaf4ff,stroke-width:1px
classDef app fill:#0c2f3a,stroke:#38bdf8,color:#e6fbff,stroke-width:2px
classDef code fill:#0b2a22,stroke:#34d399,color:#eafff6,stroke-width:1px
classDef config fill:#2a1f0b,stroke:#f59e0b,color:#fff4db,stroke-width:1px

classDef layer fill:#0b1220,stroke:#334155,color:#e5e7eb,stroke-width:1px
classDef ui fill:#0b2a5a,stroke:#60a5fa,color:#eff6ff,stroke-width:2px
classDef nav fill:#1f2937,stroke:#93c5fd,color:#f8fafc,stroke-width:2px
classDef provider fill:#2b1646,stroke:#c084fc,color:#f5e9ff,stroke-width:3px
classDef state fill:#1b1430,stroke:#a78bfa,color:#f1edff,stroke-width:1px
classDef model fill:#0b3a22,stroke:#34d399,color:#eafff6,stroke-width:2px
classDef dal fill:#4a2a0a,stroke:#fb923c,color:#fff7ed,stroke-width:2px
classDef db fill:#111827,stroke:#9ca3af,color:#f3f4f6,stroke-width:2px

class AndroidDevice,WebBrowser,AndroidRuntime,WebRuntime,SharedDart,AppBoundary platform
class UILayer,ProviderLayer,ModelLayer,DataLayer layer
```
