# osamaalhimyari/frappe_form architecture

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

- Interactive diagram: https://gitdiagram.com/osamaalhimyari/frappe_form
- Repository: https://github.com/osamaalhimyari/frappe_form

## Overview

1. **Repository purpose**
   - This is a **Flutter package** named around `frappe_form` that renders a Frappe DocType form UI, applies field-level behavior/validation, and converts user input into a response payload.
   - It is not a full app; the real product is the reusable library in `lib/`, with a separate `example/` Flutter app used to demonstrate and validate behavior across platforms.

2. **Public package boundary**
   - The main package entrypoint is `lib/frappe_form.dart`.
   - The package exposes a form-rendering surface centered on `DocFormView`, plus supporting entities, controllers, and widget overrides so consumers can embed the form into their own app and customize some field behaviors.

3. **Core data model layer**
   - `lib/src/entity/` contains the schema objects that represent the Frappe form definition: `DocForm`, `DocField`, `DocType`, `DocGeolocation`, and enumerations for field/type metadata.
   - `lib/src/model/` holds runtime/user-input models such as `DocFieldAnswer`, `DocFieldBundle`, attachments, dependency controllers, render rules, and some newer domain models like dashboard and transaction objects.
   - The presence of `*.g.dart` files indicates code generation is used for serialization and/or boilerplate reduction.

4. **Form orchestration and business logic**
   - `lib/src/logic/doc_form_controller.dart` and `doc_field_group_controller.dart` coordinate the form lifecycle, field grouping, dependency evaluation, and response assembly.
   - The `logic/enumerator/` folder defines how dependency expressions are interpreted, including arithmetic, behavior, condition, and operator handling for “depends on” rules.
   - Utility helpers under `logic/utils/` provide reusable conversion and evaluation support for booleans, dates, numbers, text, time, iteration, and parameter handling.

5. **Presentation layer architecture**
   - `lib/src/presentation/widgets/` contains the actual UI for the form and its field renderers.
   - `doc_form_view.dart` is the main composite widget; `doc_form_loading_view.dart` handles loading state.
   - Field rendering is split by capability and field family: base, text input, choice, date, boolean, attachment, location, display, group, and the newer custom field set.

6. **Field-to-widget mapping**
   - The architecture is essentially a **dispatcher**: each `DocField.type` maps to a dedicated widget implementation.
   - Examples include text editors, phone input, date/time pickers, HTML rendering, select/radio/check controls, geolocation, signatures, attachments, and table/group layouts.
   - This makes the form renderer extensible without changing the entire form container.

7. **Customization hook for unsupported or special fields**
   - `DocFormController` exposes an `onBuildFieldView` hook used to override or inject custom widgets for specific field types.
   - The README example shows this being used for dashboard-style custom fields like heatmaps and connections, which are not part of the core Frappe field set but are supported through application-level overrides.

8. **Localization and validation**
   - `lib/src/presentation/localization/` provides English and Spanish defaults plus a base localization contract for extension.
   - Validation and formatting utilities live under `presentation/utils/`, keeping input formatting, keyboard behavior, phone formatting, and validation messages separate from field widgets.
   - The form view uses these utilities to enforce required fields, read-only behavior, and dependency-based visibility/mandatory rules.

9. **External capability boundaries**
   - Some functionality is intentionally delegated to the host app rather than embedded in the package, especially attachment loading and dynamic link suggestion lookup.
   - The README also shows link and HTML rendering can rely on external plugins/services such as `url_launcher` and webview-based editors, but the package keeps those as UI integrations rather than owning backend access.

10. **Platform strategy**
   - The package is designed for Flutter’s cross-platform runtime and is exercised on Android, iOS, web, macOS, Linux, and Windows via the `example/` app.
   - The repo includes generated platform scaffolding plus web build artifacts under `docs/`, suggesting the package is also published with a Flutter web documentation/demo build.

11. **Example application as the integration reference**
   - `example/lib/main.dart` and its helper files show the intended consumption pattern: load a `DocForm`, provide callbacks like `onSubmit`, `onCancel`, `onResponse`, `fetchSuggestions`, and custom field builders, then render `DocFormView`.
   - This example app is effectively the architecture reference for consumers, demonstrating how dynamic link resolution, attachment handling, and custom field rendering flow through the package API.

12. **Generated and build support**
   - `build.yaml`, `analysis_options.yaml`, and the `*.g.dart` files indicate a codegen-oriented workflow.
   - The `docs/` directory contains compiled Flutter web assets and service worker/bootstrap files, which are deployment artifacts rather than source architecture, but they confirm the package is built and distributed with a web demo/documentation target in mind.

Main entry points: [`lib/src/presentation/widgets/doc_field_item/base/doc_field_view.dart`](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_field_item/base/doc_field_view.dart) (Field Dispatcher), [`lib/src/logic/doc_form_controller.dart`](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/logic/doc_form_controller.dart) (Form Controller), [`lib/src/presentation/widgets/doc_form_view.dart`](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_form_view.dart) (Form View), [`lib/frappe_form.dart`](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/frappe_form.dart) (frappe_form.dart)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Public API"]
  node_frappe_form_api["frappe_form.dart<br/>package entrypoint<br/>[frappe_form.dart]"]
end

subgraph group_core_lib["Core Library"]
  node_doc_form_view["Form View<br/>composite widget<br/>[doc_form_view.dart]"]
  node_doc_form_loading_view["Loading View<br/>ui state"]
  node_doc_form_controller["Form Controller<br/>orchestrator"]
  node_doc_field_group_controller["Group Controller<br/>orchestrator"]
  node_depends_logic{{"Depends Logic<br/>rule engine"}}
  node_logic_utils["Logic Utils<br/>conversion helpers<br/>[num_utils.dart]"]
  node_doc_entities[("Form Schema<br/>entity models<br/>[doc_form.dart]")]
  node_entity_enums{{"Schema Enums<br/>metadata enums<br/>[field_type.dart]"}}
  node_runtime_models[("Runtime Models<br/>answer models")]
  node_new_domain_models[("New Models<br/>extended domain<br/>[dashboard.dart]")]
  node_localization["Localization<br/>i18n"]
  node_presentation_utils["Presentation Utils<br/>format/validation"]
  node_field_dispatcher["Field Dispatcher<br/>widget family"]
  node_text_fields["Text Fields<br/>widget family"]
  node_choice_fields["Choice Fields<br/>widget family"]
  node_date_bool_fields["Date & Bool<br/>widget family"]
  node_media_loc_fields["Media & Location<br/>widget family"]
  node_display_group_fields["Display & Groups<br/>widget family"]
  node_custom_fields["Custom Fields<br/>extension widgets<br/>[heat_map_view.dart]"]
end

subgraph group_example_app["Example App"]
  node_example_main["Example Main<br/>integration app<br/>[main.dart]"]
end

node_frappe_form_api -->|"exports"| node_doc_form_view
node_frappe_form_api -->|"exports"| node_doc_entities
node_frappe_form_api -->|"exports"| node_runtime_models
node_doc_form_view -->|"uses"| node_doc_form_controller
node_doc_form_view -->|"shows"| node_doc_form_loading_view
node_doc_form_view -->|"renders"| node_field_dispatcher
node_doc_form_controller -->|"coordinates"| node_doc_field_group_controller
node_doc_form_controller -->|"evaluates"| node_depends_logic
node_doc_form_controller -->|"validates"| node_presentation_utils
node_doc_form_controller -->|"labels"| node_localization
node_doc_form_controller -->|"assembles"| node_runtime_models
node_doc_entities -->|"classified by"| node_entity_enums
node_runtime_models -->|"binds to"| node_doc_entities
node_field_dispatcher -->|"delegates"| node_text_fields
node_field_dispatcher -->|"delegates"| node_choice_fields
node_field_dispatcher -->|"delegates"| node_date_bool_fields
node_field_dispatcher -->|"delegates"| node_media_loc_fields
node_field_dispatcher -->|"delegates"| node_display_group_fields
node_field_dispatcher -.->|"extends"| node_custom_fields
node_custom_fields -.->|"hooked by"| node_doc_form_controller
node_example_main -->|"imports"| node_frappe_form_api
node_example_main -->|"builds"| node_doc_form_view
node_example_main -.->|"overrides"| node_custom_fields

click node_frappe_form_api "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/frappe_form.dart"
click node_doc_form_view "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_form_view.dart"
click node_doc_form_loading_view "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_form_loading_view.dart"
click node_doc_form_controller "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/logic/doc_form_controller.dart"
click node_doc_field_group_controller "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/logic/doc_field_group_controller.dart"
click node_depends_logic "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/logic/enumerator/doc_field_depends_on_operator.dart"
click node_logic_utils "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/logic/utils/num_utils.dart"
click node_doc_entities "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/entity/doc_form.dart"
click node_entity_enums "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/entity/enumerator/field_type.dart"
click node_runtime_models "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/model/doc_field_answer.dart"
click node_new_domain_models "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/model/new_models/dashboard.dart"
click node_localization "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/localization/doc_form_localization.dart"
click node_presentation_utils "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/utils/validation_utils.dart"
click node_field_dispatcher "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_field_item/base/doc_field_view.dart"
click node_text_fields "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_field_item/text_input/doc_field_text_view.dart"
click node_choice_fields "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_field_item/choice/doc_field_select_view.dart"
click node_date_bool_fields "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_field_item/date/doc_field_date_time_view.dart"
click node_media_loc_fields "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_field_item/location/doc_field_geolocation_view.dart"
click node_display_group_fields "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_field_item/group/doc_field_table_view.dart"
click node_custom_fields "https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/new_fields/dashboard/heat_map_view.dart"
click node_example_main "https://github.com/osamaalhimyari/frappe_form/blob/main/example/lib/main.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_frappe_form_api toneBlue
class node_doc_form_view,node_doc_form_loading_view,node_doc_form_controller,node_doc_field_group_controller,node_depends_logic,node_logic_utils,node_doc_entities,node_entity_enums,node_runtime_models,node_new_domain_models,node_localization,node_presentation_utils,node_field_dispatcher,node_text_fields,node_choice_fields,node_date_bool_fields,node_media_loc_fields,node_display_group_fields,node_custom_fields toneAmber
class node_example_main toneMint
```

## Components

### Public API

Package entrypoints and consumer-facing surface

- [frappe_form.dart](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/frappe_form.dart): package entrypoint · Exports the library surface for consumers · `lib/frappe_form.dart`

### Core Library

Domain model, orchestration, and rendering internals

- [Form View](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_form_view.dart): composite widget · Main form UI that renders and wires the entire doc form · `lib/src/presentation/widgets/doc_form_view.dart`
- [Loading View](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_form_loading_view.dart): ui state · Loading and placeholder presentation for the form · `lib/src/presentation/widgets/doc_form_loading_view.dart`
- [Form Controller](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/logic/doc_form_controller.dart): orchestrator · Owns lifecycle, response assembly, and field customization hooks · `lib/src/logic/doc_form_controller.dart`
- [Group Controller](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/logic/doc_field_group_controller.dart): orchestrator · Coordinates grouped fields and grouped field state · `lib/src/logic/doc_field_group_controller.dart`
- [Depends Logic](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/logic/enumerator/doc_field_depends_on_operator.dart): rule engine · Evaluates dependency expressions and operators for field behavior · `lib/src/logic/enumerator/doc_field_depends_on_operator.dart`
- [Logic Utils](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/logic/utils/num_utils.dart): conversion helpers · Reusable boolean, date, number, text, time, iterable, and param helpers · `lib/src/logic/utils/num_utils.dart`
- [Form Schema](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/entity/doc_form.dart): entity models · Frappe form definition objects such as DocForm, DocField, and DocType · `lib/src/entity/doc_form.dart`
- [Schema Enums](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/entity/enumerator/field_type.dart): metadata enums · Field, doc type, geometry, and feature metadata enumerations · `lib/src/entity/enumerator/field_type.dart`
- [Runtime Models](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/model/doc_field_answer.dart): answer models · User-input bundles, answers, attachments, render rules, and dependency state · `lib/src/model/doc_field_answer.dart`
- [New Models](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/model/new_models/dashboard.dart): extended domain · Dashboard, message, transaction, and special field-name models · `lib/src/model/new_models/dashboard.dart`
- [Localization](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/localization/doc_form_localization.dart): i18n · Default English and Spanish localization contracts · `lib/src/presentation/localization/doc_form_localization.dart`
- [Presentation Utils](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/utils/validation_utils.dart): format/validation · Formatting, keyboard, phone, and validation helpers for widgets · `lib/src/presentation/utils/validation_utils.dart`
- [Field Dispatcher](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_field_item/base/doc_field_view.dart): widget family · Maps field types to dedicated widget implementations · `lib/src/presentation/widgets/doc_field_item/base/doc_field_view.dart`
- [Text Fields](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_field_item/text_input/doc_field_text_view.dart): widget family · Text, numeric, password, URL, phone, markdown, and editor variants · `lib/src/presentation/widgets/doc_field_item/text_input/doc_field_text_view.dart`
- [Choice Fields](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_field_item/choice/doc_field_select_view.dart): widget family · Select, radio, checkbox, and open-choice controls · `lib/src/presentation/widgets/doc_field_item/choice/doc_field_select_view.dart`
- [Date & Bool](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_field_item/date/doc_field_date_time_view.dart): widget family · Date/time pickers and boolean toggles · `lib/src/presentation/widgets/doc_field_item/date/doc_field_date_time_view.dart`
- [Media & Location](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_field_item/location/doc_field_geolocation_view.dart): widget family · Attachments, signatures, geolocation, and related field views · `lib/src/presentation/widgets/doc_field_item/location/doc_field_geolocation_view.dart`
- [Display & Groups](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/doc_field_item/group/doc_field_table_view.dart): widget family · HTML, headings, sections, tables, tabs, columns, and list layouts · `lib/src/presentation/widgets/doc_field_item/group/doc_field_table_view.dart`
- [Custom Fields](https://github.com/osamaalhimyari/frappe_form/blob/main/lib/src/presentation/widgets/new_fields/dashboard/heat_map_view.dart): extension widgets · Application-specific field views such as dashboard, link, barcode, color, and multi-select · `lib/src/presentation/widgets/new_fields/dashboard/heat_map_view.dart`

### Example App

Cross-platform integration reference

- [Example Main](https://github.com/osamaalhimyari/frappe_form/blob/main/example/lib/main.dart): integration app · Example app entrypoint showing how to embed and configure the form · `example/lib/main.dart`

## Connections

- frappe_form.dart → Form View: exports · Package entrypoint exposes the main form surface
- frappe_form.dart → Form Schema: exports · Public API includes schema objects
- frappe_form.dart → Runtime Models: exports · Public API includes runtime answer/model types
- Form View → Form Controller: uses · View delegates lifecycle and submission coordination
- Form View → Loading View: shows · Switches to loading state while data is unavailable
- Form View → Field Dispatcher: renders · Builds field widgets through the type dispatcher
- Form Controller → Group Controller: coordinates · Controller manages grouped field orchestration
- Form Controller → Depends Logic: evaluates · Applies dependency expressions for visibility and requirements
- Form Controller → Presentation Utils: validates · Uses formatting and validation helpers for input behavior
- Form Controller → Localization: labels · Reads localized strings for validation and UI text
- Form Controller → Runtime Models: assembles · Collects answers and builds response payloads
- Form Schema → Schema Enums: classified by · Schema objects are parameterized by enumerated metadata
- Runtime Models → Form Schema: binds to · Runtime answers are shaped by schema definition
- Field Dispatcher → Text Fields: delegates · Routes text-like fields to specialized inputs
- Field Dispatcher → Choice Fields: delegates · Routes choice-based fields to selection widgets
- Field Dispatcher → Date & Bool: delegates · Routes date and boolean fields to dedicated controls
- Field Dispatcher → Media & Location: delegates · Routes media, attachment, and location fields
- Field Dispatcher → Display & Groups: delegates · Routes structural and display-only field families
- Field Dispatcher → Custom Fields: extends · Supports host-app overrides and special field renderers
- Custom Fields → Form Controller: hooked by · Custom field builders are injected through the controller hook
- Example Main → frappe_form.dart: imports · Example app consumes the package entrypoint
- Example Main → Form View: builds · Example composes the main form widget in a host app
- Example Main → Custom Fields: overrides · Demonstrates custom builders for unsupported field types