# dhwani-ris/frappe-mobile-sdk architecture

> Architecture diagram of the GitHub repository dhwani-ris/frappe-mobile-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dhwani-ris/frappe-mobile-sdk
- Repository: https://github.com/dhwani-ris/frappe-mobile-sdk

## Overview

1. **Repository role**
   - This is a **Flutter/Dart package**, not a standalone app. The public entrypoint is `lib/frappe_mobile_sdk.dart`, which re-exports a layered SDK for Frappe/ERPNext mobile clients.
   - The package is meant to be embedded inside another Flutter app, while `example/` shows a complete integration.

2. **Top-level architecture**
   - The SDK is organized into four main runtime layers:
     - **API layer** for HTTP access to Frappe.
     - **Service layer** for auth, metadata, permissions, sync, workflows, and offline orchestration.
     - **Database layer** for local persistence with SQLite.
     - **UI layer** for ready-made screens and dynamic form widgets.
   - `FrappeSDK` in `lib/src/sdk/frappe_sdk.dart` is the high-level façade that wires these layers together.

3. **External boundary: Frappe server + companion app**
   - The package talks to a **Frappe/ERPNext backend** over HTTP.
   - Several features depend on the separate **Frappe Mobile Control** server app, especially app status checks, mobile auth APIs, translations, and configuration endpoints.
   - This means the client SDK is only one side of a broader mobile system; server capabilities strongly shape the SDK behavior.

4. **Authentication and session management**
   - Auth is handled by `AuthService` plus `FrappeClient` auth helpers.
   - Supported flows include username/password, mobile OTP, API key, and OAuth 2.0 with PKCE.
   - Tokens are persisted in the local database and/or secure storage, and session restore is a first-class startup path. This makes login state durable across app restarts.

5. **API layer**
   - `lib/src/api/` contains the direct Frappe HTTP surface:
     - document CRUD
     - DocType metadata/listing
     - file attachments
     - custom method calls
     - query building
   - This layer is the clean boundary between Dart code and the server API; higher layers depend on it, but not vice versa.

6. **Offline-first data architecture**
   - The core offline design is a **two-store local model**: a legacy JSON/blob store plus normalized per-DocType tables.
   - `OfflineRepository` and `LocalWriter` implement dual-write behavior so local edits are immediately available for reads and link lookups.
   - `UnifiedResolver` provides a single read path that prefers local normalized tables and refreshes from the API in the background when online.

7. **Sync subsystem**
   - Sync is split into **pull** and **push** engines under `lib/src/sync/`.
   - Pull uses cursor-based, phased synchronization with pagination and bounded parallelism.
   - Push assembles payloads, handles UUID-to-server-name rewriting, idempotency, conflict mapping, and response writeback.
   - `SyncService` and `SyncController` expose the operational sync surface used by UI and app logic, including pause/resume, retry, conflict resolution, and delete-cascade preview/accept flows.

8. **Local persistence and schema management**
   - SQLite is the local storage backbone via `AppDatabase`, DAOs, entities, and schema helpers.
   - The database stores auth tokens, metadata, permissions, translations, outbox rows, pending attachments, security events, and the denormalized document tables.
   - The schema layer includes migration support, search normalization, table naming, and schema application logic, which is important because offline sync depends on stable local structure.

9. **Metadata-driven forms and runtime UI**
   - Forms are generated from server metadata: `DocTypeMeta`, `DocField`, `Document`, workflow metadata, and related models.
   - `FrappeFormBuilder`, `FormScreen`, `DocumentListScreen`, and `DoctypeListScreen` are the main UI entry points.
   - Field widgets are selected dynamically by field type, with a large widget set under `lib/src/ui/widgets/fields/` for text, numeric, date/time, link, child table, attachment, image, password, phone, geolocation, and workflow/button behavior.

10. **Workflow and business-rule layer**
    - Workflow handling is explicitly modeled, not embedded in the UI.
    - `WorkflowService` fetches transitions and applies workflow actions, while `FormScreen` changes its actions based on doc status and workflow state.
    - This separates business process behavior from rendering and persistence.

11. **Supporting runtime services**
    - Services under `lib/src/services/` coordinate the app’s behavior across domains: meta loading, permissions, translations, session user state, dependency graphs, link option resolution, offline transition handling, and error capture.
    - These services act as the orchestration layer between API, database, sync, and UI.

12. **Platform and security boundaries**
    - Android and iOS native code exists under `android/` and `ios/` for security-related behavior via platform channels.
    - `FrappeSecurityPlugin` on both platforms suggests device/app security checks or protection hooks are implemented natively, with Dart-side wrappers in `lib/src/security/`.

13. **App control and startup gating**
    - `FrappeAppGuard` checks server-side app status/version before the app proceeds.
    - This creates a launch-time control boundary: the client can be blocked, forced to update, or allowed through based on backend policy.
    - It is distinct from authentication; it governs whether the app is permitted to run at all.

14. **Example app, tests, and delivery pipeline**
    - `example/` demonstrates how to compose the SDK into a real Flutter app, including app config, login, and navigation.
    - The large `test/` tree reflects the package’s architecture: API, database, sync, services, UI, and widget behavior are all independently testable.
    - CI/release automation in `.github/workflows/` and related config files supports formatting, analysis, testing, semantic commits, and versioned releases.

15. **How data flows through the system**
    - Typical flow: app startup → app guard and session restore → metadata/auth loading → local database initialization → UI renders from local/meta state → user edits hit the repository/local writer → sync engine pushes/pulls with the server → results are written back locally and reflected in UI state streams.
    - The main architectural boundary is between **server-backed Frappe APIs** and **local offline state**, with the SDK’s services and sync engine bridging the two.

Main entry points: [`lib/src/sdk/frappe_sdk.dart`](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/sdk/frappe_sdk.dart) (FrappeSDK), [`lib/src/database/app_database.dart`](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/database/app_database.dart) (App database), [`lib/src/api`](https://github.com/dhwani-ris/frappe-mobile-sdk/tree/develop/lib/src/api) (API services), [`lib/src/services/offline_repository.dart`](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/services/offline_repository.dart) (Offline repo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_boundary["External boundary"]
  node_frappe_server[("Frappe server<br/>backend API")]
  node_mobile_control[("Control app<br/>server companion")]
end

subgraph group_core["SDK core"]
  node_sdk_entry["SDK entry<br/>public export"]
  node_frappe_sdk{{"FrappeSDK<br/>façade<br/>[frappe_sdk.dart]"}}
  node_api_client["HTTP client<br/>api client<br/>[client.dart]"]
  node_api_services["API services<br/>document/query APIs"]
  node_auth_service["Auth service<br/>session/auth<br/>[auth_service.dart]"]
  node_meta_service["Meta service<br/>metadata orchestration<br/>[meta_service.dart]"]
  node_offline_repo["Offline repo"]
  node_local_writer["Local writer<br/>local persistence writer<br/>[local_writer.dart]"]
  node_unified_resolver["Unified resolver<br/>read resolver"]
  node_workflow_service["Workflow service<br/>business rules"]
end

subgraph group_storage["Local storage"]
  node_db[("App database<br/>sqlite DB<br/>[app_database.dart]")]
  node_schema["Schema layer<br/>schema/migrations"]
  node_daos["DAOs<br/>data access"]
end

subgraph group_sync["Sync engine"]
  node_pull_engine["Pull engine<br/>sync pull<br/>[pull_engine.dart]"]
  node_push_engine["Push engine<br/>sync push<br/>[push_engine.dart]"]
  node_sync_service{{"Sync service<br/>sync orchestration<br/>[sync_service.dart]"}}
end

subgraph group_ui["Runtime UI"]
  node_form_screen["Form screen<br/>dynamic form UI<br/>[form_screen.dart]"]
  node_list_screens["List screens<br/>navigation UI"]
  node_field_widgets["Field widgets<br/>widget set"]
  node_app_guard{{"App guard<br/>startup gate<br/>[app_guard.dart]"}}
end

subgraph group_platform["Native security"]
  node_security_native{{"Security plugin<br/>native channel"}}
end

node_sdk_entry -->|"re-exports"| node_frappe_sdk
node_frappe_sdk -->|"uses"| node_api_client
node_frappe_sdk -->|"uses"| node_api_services
node_frappe_sdk -->|"orchestrates"| node_auth_service
node_frappe_sdk -->|"orchestrates"| node_meta_service
node_frappe_sdk -->|"orchestrates"| node_offline_repo
node_offline_repo -->|"dual-writes"| node_local_writer
node_offline_repo -->|"reads via"| node_unified_resolver
node_api_services -->|"http"| node_frappe_server
node_api_services -->|"http"| node_mobile_control
node_auth_service -->|"persists"| node_db
node_meta_service -->|"caches"| node_db
node_db -->|"managed by"| node_schema
node_db -->|"accessed by"| node_daos
node_sync_service -->|"coordinates"| node_pull_engine
node_sync_service -->|"coordinates"| node_push_engine
node_pull_engine -->|"syncs from"| node_frappe_server
node_push_engine -->|"syncs to"| node_frappe_server
node_workflow_service -->|"fetches/actions"| node_frappe_server
node_form_screen -->|"renders from"| node_meta_service
node_form_screen -->|"composes"| node_field_widgets
node_list_screens -->|"reads from"| node_unified_resolver
node_app_guard -->|"checks"| node_mobile_control
node_security_native -.->|"supports"| node_frappe_sdk

click node_sdk_entry "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/frappe_mobile_sdk.dart"
click node_frappe_sdk "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/sdk/frappe_sdk.dart"
click node_api_client "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/api/client.dart"
click node_api_services "https://github.com/dhwani-ris/frappe-mobile-sdk/tree/develop/lib/src/api"
click node_auth_service "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/services/auth_service.dart"
click node_meta_service "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/services/meta_service.dart"
click node_offline_repo "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/services/offline_repository.dart"
click node_local_writer "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/services/local_writer.dart"
click node_unified_resolver "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/query/unified_resolver.dart"
click node_db "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/database/app_database.dart"
click node_schema "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/database/schema_applier.dart"
click node_daos "https://github.com/dhwani-ris/frappe-mobile-sdk/tree/develop/lib/src/database/daos"
click node_pull_engine "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/sync/pull_engine.dart"
click node_push_engine "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/sync/push_engine.dart"
click node_sync_service "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/services/sync_service.dart"
click node_workflow_service "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/services/workflow_service.dart"
click node_form_screen "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/ui/form_screen.dart"
click node_list_screens "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/ui/document_list_screen.dart"
click node_field_widgets "https://github.com/dhwani-ris/frappe-mobile-sdk/tree/develop/lib/src/ui/widgets/fields"
click node_app_guard "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/ui/app_guard.dart"
click node_security_native "https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/android/src/main/kotlin/com/dhwaniris/frappe_mobile_sdk/FrappeSecurityPlugin.kt"

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_frappe_server,node_mobile_control toneBlue
class node_sdk_entry,node_frappe_sdk,node_api_client,node_api_services,node_auth_service,node_meta_service,node_offline_repo,node_local_writer,node_unified_resolver,node_workflow_service toneAmber
class node_db,node_schema,node_daos toneMint
class node_pull_engine,node_push_engine,node_sync_service toneRose
class node_form_screen,node_list_screens,node_field_widgets,node_app_guard toneIndigo
class node_security_native toneTeal
```

## Components

### External boundary

Remote Frappe server and companion mobile control app.

- **Frappe server**: backend API · Remote Frappe/ERPNext HTTP surface for documents, metadata, auth, and workflows.
- **Control app**: server companion · Separate mobile control service for app status, translations, and configuration.

### SDK core

Public façade and layered runtime inside the Flutter package.

- [SDK entry](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/frappe_mobile_sdk.dart): public export · Package entrypoint that re-exports the mobile SDK surface. · `lib/frappe_mobile_sdk.dart`
- [FrappeSDK](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/sdk/frappe_sdk.dart): façade · High-level orchestrator that wires API, services, persistence, sync, and UI. · `lib/src/sdk/frappe_sdk.dart`
- [HTTP client](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/api/client.dart): api client · Core REST client and auth helpers for server communication. · `lib/src/api/client.dart`
- [API services](https://github.com/dhwani-ris/frappe-mobile-sdk/tree/develop/lib/src/api): document/query APIs · Document CRUD, DocType metadata, attachments, custom methods, and query building. · `lib/src/api`
- [Auth service](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/services/auth_service.dart): session/auth · Handles password, OTP, API key, OAuth2/PKCE, and session restore. · `lib/src/services/auth_service.dart`
- [Meta service](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/services/meta_service.dart): metadata orchestration · Loads DocType metadata, permissions, translations, and related runtime metadata. · `lib/src/services/meta_service.dart`
- [Offline repo](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/services/offline_repository.dart): offline repository · Dual-write repository bridging reads, local writes, lookups, and online refresh. · `lib/src/services/offline_repository.dart`
- [Local writer](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/services/local_writer.dart): local persistence writer · Applies edits into local normalized tables and legacy storage for immediate offline reads. · `lib/src/services/local_writer.dart`
- [Unified resolver](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/query/unified_resolver.dart): read resolver · Single read path preferring local normalized data and backfilling from API when online. · `lib/src/query/unified_resolver.dart`
- [Workflow service](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/services/workflow_service.dart): business rules · Fetches transitions and applies workflow actions separate from rendering. · `lib/src/services/workflow_service.dart`

### Local storage

SQLite-backed persistence, schema, and normalized document tables.

- [App database](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/database/app_database.dart): sqlite DB · SQLite backbone storing auth, metadata, permissions, translations, outbox, attachments, and documents. · `lib/src/database/app_database.dart`
- [Schema layer](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/database/schema_applier.dart): schema/migrations · Table naming, schema application, search normalization, and migration support. · `lib/src/database/schema_applier.dart`
- [DAOs](https://github.com/dhwani-ris/frappe-mobile-sdk/tree/develop/lib/src/database/daos): data access · Persistence access layer for auth tokens, metadata, permissions, outbox, attachments, and security state. · `lib/src/database/daos`

### Sync engine

Pull/push pipelines and sync state coordination.

- [Pull engine](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/sync/pull_engine.dart): sync pull · Cursor-based phased synchronization with pagination and bounded parallelism. · `lib/src/sync/pull_engine.dart`
- [Push engine](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/sync/push_engine.dart): sync push · Builds payloads, rewrites UUIDs, handles idempotency, conflicts, and writeback. · `lib/src/sync/push_engine.dart`
- [Sync service](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/services/sync_service.dart): sync orchestration · Operational sync API exposed to app logic, including retry, pause/resume, and conflict flows. · `lib/src/services/sync_service.dart`

### Runtime UI

Generated forms, lists, login, and sync/status screens.

- [Form screen](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/ui/form_screen.dart): dynamic form UI · Metadata-driven document editor that adapts actions and fields to server state. · `lib/src/ui/form_screen.dart`
- [List screens](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/ui/document_list_screen.dart): navigation UI · Document and Doctype list entry points for browsing and selecting records. · `lib/src/ui/document_list_screen.dart`
- [Field widgets](https://github.com/dhwani-ris/frappe-mobile-sdk/tree/develop/lib/src/ui/widgets/fields): widget set · Dynamic field implementations for text, link, child table, attachment, date/time, media, and workflow behavior. · `lib/src/ui/widgets/fields`
- [App guard](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/lib/src/ui/app_guard.dart): startup gate · Checks server-side app status/version before allowing the app to proceed. · `lib/src/ui/app_guard.dart`

### Native security

Platform-channel security hooks on Android and iOS.

- [Security plugin](https://github.com/dhwani-ris/frappe-mobile-sdk/blob/develop/android/src/main/kotlin/com/dhwaniris/frappe_mobile_sdk/FrappeSecurityPlugin.kt): native channel · Android and iOS platform-channel security checks and protection hooks. · `android/src/main/kotlin/com/dhwaniris/frappe_mobile_sdk/FrappeSecurityPlugin.kt`

## Connections

- SDK entry → FrappeSDK: re-exports · Public package API exposes the main SDK façade.
- FrappeSDK → HTTP client: uses · Façade configures network access and auth.
- FrappeSDK → API services: uses · Façade exposes the direct server API layer.
- FrappeSDK → Auth service: orchestrates · Startup and login flows depend on durable session handling.
- FrappeSDK → Meta service: orchestrates · Loads metadata and related runtime state.
- FrappeSDK → Offline repo: orchestrates · Coordinates offline-first reads and writes.
- Offline repo → Local writer: dual-writes · Writes local edits into normalized and legacy stores.
- Offline repo → Unified resolver: reads via · Uses a single read path that prefers local data.
- API services → Frappe server: http · Direct Frappe server boundary for CRUD, metadata, files, and queries.
- API services → Control app: http · Uses companion app endpoints for mobile-specific capabilities.
- Auth service → App database: persists · Stores tokens and session state locally for restore on startup.
- Meta service → App database: caches · Caches metadata, permissions, and translations locally.
- App database → Schema layer: managed by · Database structure is defined and evolved by schema helpers and migrations.
- App database → DAOs: accessed by · DAOs provide the persistence boundary for runtime services.
- Sync service → Pull engine: coordinates · Sync service drives pull phases and progress state.
- Sync service → Push engine: coordinates · Sync service drives push/flush behavior and retries.
- Pull engine → Frappe server: syncs from · Pulls server changes into local state.
- Push engine → Frappe server: syncs to · Pushes local changes and receives writeback responses.
- Workflow service → Frappe server: fetches/actions · Workflow state and transitions come from server metadata and actions.
- Form screen → Meta service: renders from · Forms are built from metadata and doc fields.
- Form screen → Field widgets: composes · Selects field widgets dynamically by field type.
- List screens → Unified resolver: reads from · List views source documents through the unified local-first path.
- App guard → Control app: checks · Launch gating depends on remote app status policy.
- Security plugin → FrappeSDK: supports · Native security checks are wrapped by Dart-side security services.
