Form Module Architecture

Scope

The Form module spans the Angular packages under web/projects/packages/@barcoding/modules/form, the shared renderer in @barcoding/core, the Front widget (web/projects/front/src/widgets/widget-form-front), and LoopBack models/controllers inside api/b3api. This guide captures implementation details for engineers extending widgets, APIs, or reports.

Data Model

Entity	Source	Notes
Form	api/b3api/src/models/form.model.ts	Metadata wrapper (name, category, status) with form_revision_id pointing to the active revision.
FormRevision	api/b3api/src/models/form-revision.model.ts	Stores JSON definition, revision string/number, publish metadata, and change notes.
FormRelation	api/b3api/src/models/form-relation.model.ts	Links a form to a module/object pair and stores required plus validation_scope (per_user, per_object, global).
FormResult	api/b3api/src/models/form-result.model.ts	Captured responses, progress, signature data, contextual IDs (module/object/part/document/NCR), and definition_snapshot for immutability.

Controllers live under api/b3api/src/controllers/form*.controller.ts and expose CRUD plus custom verbs (/form-revisions/{id}/publish, /form-results/{id}/complete, /form-results/{id}/sign).

Supported Field Types

Implementation: web/projects/packages/@barcoding/core/src/lib/form-renderer/form-renderer.interface.ts

Field	Key Properties	Stored Shape	Validation Highlights
radio / radio-na	options: RadioOption[]	{ value: 'optionId' } (radio-na includes an optional N/A value)	Required check ensures a selection; N/A counts as valid when enabled.
radio-conditional	conditionalInput defines trigger value + prompt.	{ value: 'optionId', conditionalValue?: string }	FormRendererService.validateField enforces the follow-up comment when trigger option is chosen and flag is required.
measurement	unit, validation (nominal ± tolerance or min/max).	Numeric scalar stored inside FieldResult.value.	Validates ranges/tolerances and tags out-of-tolerance values with status: 'out_of_tolerance' for analytics and UI badges.
matrix	rows, columns.	{ [rowId]: columnId }	Renderer insists each row maps to a column and analytics counts selections per column/row.
input-table	tabular rows x columns.	{ [rowId]: { [colId]: value } }	Requires filled cells for required tables and calculates per-column min/max/avg for analytics.

All fields support conditional visibility (FieldCondition), info banners, and required flags that feed into progress.

Backend Widgets (Angular Backend App)

Each widget has its own deep dive under Widgets ➜ Form. Use the links to jump straight to implementation notes:

• Form Info – summary card + quick edit.
• Form Revisions – revision grid, publish/set-active workflow.
• Form Relations – relation grid + dialog controlling required/scope flags.
• Form Results – object-scoped results list with view/print/delete.
• Form Results Analytics – charting widget + summary report trigger.

Core list/dialog components (formList, formForm) remain inside the module package and rely on standard Angular patterns with FormControllerService and Kendo inputs.

Frontline Widget (Angular Front App)

• widget-form-front – session-bound runner that launches the renderer dialog.

Renderer & Autosave

Renderer mechanics live in web/projects/packages/@barcoding/core/src/lib/form-renderer/* and components/form-fill-dialog. Refer to those directories for implementation details; widget docs cover how the dialog interacts with the renderer.

Reporting Pipeline

• Form Result Print
  • Worker: api/b3api/src/services/reports/form_result_print/form_result_print.c.ts.
  • Registers via migration 20260205031206_create_form_result_print_report.ts.
  • Includes context relations (NCR, Document, Part, Module), renders Tailwind template, supports inline HTML or PDF file output.
• Form Summary Report
  • Worker: api/b3api/src/services/reports/form_summary_report/form_summary_report.c.ts.
  • Registered via migration 20260209120000_add_form_analytics_widget_and_report.ts.
  • Aggregates completed results, computes completion rate, date range, and per-field stats matching the analytics widget visuals.

Both workers leverage ReportService.generateReport from the backend app and deliver HTML to the requesting user (options_interface.delivery.instant = true).

Extension Notes

• Adding a New Field Type: update FormField union + supporting components under form-renderer/components/fields, extend FormRendererService.validateField, and enhance analytics builder functions when necessary.
• Custom Result Filters: widget-form-front currently scopes by document_so_line_id. Add new relation fields in buildRelationFields() and API filters if the widget needs to react to different contexts.
• Migrations: use Knex migrations under api/b3api/src/knex_migrations/ for schema changes. Table names follow PascalCase (e.g., FormResultAttachment).

Related Docs

• Form Module Overview
• Tool Calibration Architecture