How dhwani-ris/frappe-mobile-sdk works
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: frappe_sdk.dart FrappeSDK · app_database.dart App database · api API services · offline_repository.dart Offline repo
Components 23
External boundary
Remote Frappe server and companion mobile control app.
- Frappe server · Remote Frappe/ERPNext HTTP surface for documents, metadata, auth, and workflows.
- Control app · Separate mobile control service for app status, translations, and configuration.
SDK core
Public façade and layered runtime inside the Flutter package.
- SDK entry · Package entrypoint that re-exports the mobile SDK surface.
lib/frappe_mobile_sdk.dart - FrappeSDK · High-level orchestrator that wires API, services, persistence, sync, and UI.
lib/src/sdk/frappe_sdk.dart - HTTP client · Core REST client and auth helpers for server communication.
lib/src/api/client.dart - API services · Document CRUD, DocType metadata, attachments, custom methods, and query building.
lib/src/api - Auth service · Handles password, OTP, API key, OAuth2/PKCE, and session restore.
lib/src/services/auth_service.dart - Meta service · Loads DocType metadata, permissions, translations, and related runtime metadata.
lib/src/services/meta_service.dart - Offline repo · Dual-write repository bridging reads, local writes, lookups, and online refresh.
lib/src/services/offline_repository.dart - Local writer · Applies edits into local normalized tables and legacy storage for immediate offline reads.
lib/src/services/local_writer.dart - Unified resolver · Single read path preferring local normalized data and backfilling from API when online.
lib/src/query/unified_resolver.dart - Workflow service · 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 · SQLite backbone storing auth, metadata, permissions, translations, outbox, attachments, and documents.
lib/src/database/app_database.dart - Schema layer · Table naming, schema application, search normalization, and migration support.
lib/src/database/schema_applier.dart - DAOs · 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 · Cursor-based phased synchronization with pagination and bounded parallelism.
lib/src/sync/pull_engine.dart - Push engine · Builds payloads, rewrites UUIDs, handles idempotency, conflicts, and writeback.
lib/src/sync/push_engine.dart - Sync service · 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 · Metadata-driven document editor that adapts actions and fields to server state.
lib/src/ui/form_screen.dart - List screens · Document and Doctype list entry points for browsing and selecting records.
lib/src/ui/document_list_screen.dart - Field widgets · Dynamic field implementations for text, link, child table, attachment, date/time, media, and workflow behavior.
lib/src/ui/widgets/fields - App guard · 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 · Android and iOS platform-channel security checks and protection hooks.
android/src/main/kotlin/com/dhwaniris/frappe_mobile_sdk/FrappeSecurityPlugin.kt
Connections 24
- 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.