Depicter

The Depicter is the primary façade for authoring generation scripts in Gen-X. It provides a high-level Go API for assembling a complete application depiction — models, forms, views, relations, validations, routers, and file resources — without interacting directly with lower-level handlers, appliers, or configurators. Every method on the Depicter coordinates one or more of these internal layers so that your depiction script stays clean and readable.

Table of Contents

• Public API
  • File / Directory Operations
  • Model Operations
  • Form Operations
  • Validation
  • Section / View Operations
  • Router Operations
  • MAE / Step Operations
  • Menu, Commands & Configuration
  • Data Helpers
• Private Methods
  • Project Setup
  • Actor Creation (internal)
  • MAE / Maestro Internals
  • Service Importing
  • Section Management (internal)
  • Form Internals
  • File Walking
  • Model Lookup
  • File Copy Helpers
• The Blue-Lila CRUD Approach
  • Actors (See, Display, Show, Perform)

Public API

File / Directory Operations

These methods manage how static files and directories are copied from the project’s input directory into the generated output. Use them when your application needs custom assets, pre-written Go files, or entire directory trees that Gen-X should include verbatim.

💡 Tip: Use CopiesOverwrittenFiles at the end of your depiction script to apply any handcrafted overrides to the generated code. Files annotated with // |@@| W are treated as intentional overwrites and will replace the generated versions.

Model Operations

Models are the foundational domain entities of your application. Each call to AddModel triggers the full model creation pipeline — services, structures, CRUD actors, and utility fields are all set up automatically by the underlying ModelCreateApplier.

💡 Tip: Pass crud: true to AddModel to generate the full Create / Read / Update / Delete actor set automatically. Pass crud: false for system or lookup models that do not need user-facing CRUD views.

Form Operations

Forms define the input structures used by CRUD actors. When you add a form field, the underlying FormFieldCreateApplier creates the corresponding structure field and wires it into the actor’s presenter automatically.

📝 Note: Form field names should match the corresponding model field names by convention. The generation pipeline uses naming patterns to link forms, presenters, and validators together — diverging from the convention requires explicit wiring.

Validation

Validation rules are attached to form fields or model fields and are enforced at runtime by the generated form validator services. Each method below registers a specific kind of validation constraint.

Section / View Operations

Sections are the building blocks of generated HTML views. Each actor owns a view, and each view is composed of ordered sections. The methods below let you add, reorder, hide, or extend sections within any view in the project.

Router Operations

Routers register the HTTP endpoints for your application. The Depicter supports both public and exchange routers, each resulting in a Gin router group wired into the project.

💡 Tip: Use AddPublicRouter for unauthenticated routes and AddExchangeRouter for API or AJAX endpoints that communicate with the frontend asynchronously.

MAE / Step Operations

Maestros (MAEs) are the controller layer of the generated application. These methods let you extend existing Maestros with new steps, adjust sort configurations, and modify step data without touching the generated code directly.

📝 Note: Step positions are 1-based and sequential within a Maestro. Inserting a step at an existing position shifts later steps forward automatically.

Menu, Commands & Configuration

These methods handle project-level concerns: navigation menus, CLI commands, port configuration, file resources, and dependency declarations. Call them after the core model and actor setup to finalize the project shape.

Data Helpers

These helpers produce pre-marshalled data payloads used when configuring model fields with specific formats or constraints.

💡 Tip: Pass the result of StringDataEnum directly as the data argument when creating a string model field that should be restricted to a fixed set of values. The generated form will render an appropriate select input automatically.

Private Methods

This section lists all unexported (private) methods of the Depicter struct in src/srv/depicters/depicter.go. These methods are internal helpers used by the public API; they are not intended to be called directly from outside the package.

Project Setup

These private methods handle the creation of output directories and the management of service dependency relationships during generation.

Actor Creation (internal)

These private methods create the different kinds of actors that make up the user-facing layer of a generated application. Each actor kind generates a distinct Maestro structure with the appropriate views and routes. See The Blue-Lila CRUD Approach for an explanation of each actor kind.

MAE / Maestro Internals

These methods manipulate the internal structure of Maestro services — adding fields to input/output contracts, locating Maestros by name, and managing custom function code.

Service Importing

These methods import existing Go files into the generation pipeline as free services, allowing handcrafted code to be included alongside generated code.

Section Management (internal)

These private methods perform the low-level mutations on view section lists: creating, removing, reordering, and inserting sections while keeping position values consistent.

Form Internals

These private helpers look up form fields by name and create form fields on named forms, used internally by the public AddFormField methods.

File Walking

These methods implement the filepath.Walk callback used by CopiesOverwrittenFiles to identify and copy files marked for overwrite.

Model Lookup

These panic-on-miss helpers are used throughout the Depicter to retrieve models and model fields by name, providing an early failure signal when a depiction script references a non-existent entity.

File Copy Helpers

These thin wrappers over the file system operations print a progress indicator for each file or directory copied during generation.

The Blue-Lila CRUD Approach

Gen-X generates applications using a structured actor model that classifies every user-facing operation by its intent. Rather than generating generic CRUD screens, the Blue-Lila approach distinguishes between operations that display information and operations that perform changes. This distinction drives which Maestro structure, views, and routes are generated for each part of the application.

Actors (See, Display, Show, Perform)

An Actor represents a single user-facing operation in the generated application. Each actor is associated with a model (or a combination of models) and produces a Maestro, a view, and one or more routes. The actor’s kind determines what is generated.

The four actor kinds and their relationships are:

• Display — A read-only view that presents information about one or more entities. A Display actor generates a single GET route and a view with zero or more informational sections. It can be associated with zero or more Perform actors that offer actions from within that view. Use Display for consumer-facing information pages where the user reads but does not submit data directly.

• See — A read actor that always pairs with exactly one Perform actor. See generates a GET route that renders a form; Perform generates the corresponding POST route that processes the form submission. Together they form a read/write pair — See prepares and presents the form, Perform handles the submit. Use See + Perform for any operation that involves a user filling in and submitting data (create, edit, or any custom form action).

• Show — A data-centric read actor used for standard CRUD detail views. Show is closely tied to a single model and generates the entity detail page. It sits within the CRUD actor set created automatically when AddModel is called with crud: true.

• Perform — A write actor that handles form submission or any state-changing operation. Perform actors are always paired with either a See actor (for form-based flows) or attached to a Display actor (for inline actions). A standalone Perform actor without a See or Display parent is used for non-visual operations such as background processing or API endpoints.

The key rules of the actor model:

• See always has exactly 1 Perform — the See/Perform pair is the canonical read/write pair for form-based interactions.
• Display has 0–N Performs — a display page can expose zero actions (pure read) or multiple action buttons, each backed by its own Perform actor.
• Show is data-centric (CRUD) — it belongs to the standard CRUD set and presents a single entity in detail.

📝 Note: addSee is marked deprecated in the internal API. Prefer addDisplay for new actors. The Display kind is more flexible and covers all use cases previously handled by See.

Next Steps

• Architecture Overview — Understand how the full generation pipeline works
• Appliers — See what happens after each Depicter call triggers an applier