sozsoft/sozsoft-platform
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
sozsoft-platform/.github/instructions/ai.instructions.md
Sedat ÖZTÜRK 59ec8950a3 Custom Component ve Wizard Import/Export özelliği
2026-09-05 21:20:18 +03:00

34 KiB
Raw Blame History

Dynamic Low-Code Platform - AI Instruction and Operating Manual

1. Purpose

This document defines how AI should think, decide, and produce outputs for this platform.

Primary objective:

  • Maximize delivery through runtime configuration.
  • Minimize custom code.
  • Preserve platform consistency, security, and tenant isolation.

Primary principle:

  • Configuration first, code last.

Companion documents (this file wins on conflict):

Document Scope
lowcode.instructions.md Authoring reference: exact schemas, enum values and worked examples for producing wizard screens, editor scripts, custom components, SQL objects and endpoints. Read it before writing any artifact.
lowcode-reference.instructions.md Capability inventory: field-by-field contract of every ListForm/ListFormField JSON column, chart and pivot options, SQL command hooks, Visual Designer toolbox, the scheduled-mail module and (§12) every ready-made screen under the Saas and Administration menus. Sweep its §0 checklist before producing a screen or component; a request whose answer already exists as a platform screen (§12.5) is configured there, not rebuilt.
dotnet.instructions.md Binding code standard for everything under api/
list.instructions.md Step-by-step procedure for adding a module / list through seeders
../../README.md Technical map: what exists, where it lives, how it is wired
../../CLAUDE.md Operating rules and standing defaults for AI agents in this repo

2. Platform Scope

Core stack:

  • Backend: C# .NET 10 (C# 14) + ABP 10.x — kod standardı: dotnet.instructions.md
  • Frontend: React 19 + DevExtreme
  • Database: SQL Server (dynamic datasource support)
  • Cache: Redis
  • Background jobs: Hangfire + ABP Background Workers

System nature:

  • Runtime configurable application engine
  • Multi-tenant SaaS foundation
  • Low-code / no-code first

3. Non-Negotiable Rules

  1. Do not propose new custom React component/page development for standard feature requests.
  2. Build new screens using platform configuration mechanisms.
  3. Every proposal must include tenant and permission design.
  4. Never bypass platform authorization patterns.
  5. Never hardcode secrets, tenant ids, or connection strings.
  6. Stay inside the framework; ask before stepping out. The platform may extend itself through its own mechanisms (seed artifacts; adding a missing event, prop, or small backward-compatible capability to an existing UI component — when Developer Kit tooling builds ~70% of the requested component, the rest is completed with such small additions, never with a new component; backward-compatible additions to script recipes / editor options / tokens). Anything beyond that — a new React component or page, a new toolbox family, core engine changes (ListForm runtime, seeders, code generator, auth, DataSourceManager, dispatcher/compiler), new ABP entity/module/migration, platform table schema changes, new NuGet/npm dependencies, Routes in MenusData.json, new external integrations — is out of frame: finish everything that fits inside the frame first, then ask the user with a single question (why configuration is insufficient, the smallest change that works, files touched, rollback) and proceed only with explicit approval. Approval is per request and does not carry over. Full lists: lowcode.instructions.md §0.8.

Exception policy:

  • Code-level React or backend development can be considered only if user explicitly requests code implementation and configuration path is insufficient.
  • If exception is required, AI must explain why configuration-based options are not enough.
  • Never say "cannot be done": the answer is either an in-frame build or an approval question.

4. Decision Flow (Mandatory)

For every request, apply this order:

  1. Dynamic configuration with existing ListForm ecosystem
  2. SQL Query Manager + Custom Endpoint
  3. Dynamic Service
  4. Code change (last resort, justification required)

5. Architecture Guardrails

Backend (ABP):

  • Respect modular boundaries.
  • Prefer application services over ad-hoc endpoints.
  • Keep permissions explicit and auditable.

Frontend (React + DevExtreme):

  • Use existing dynamic view infrastructure.
  • Keep component behavior metadata-driven.
  • Preserve route, menu, and permission coherence.

Data:

  • SQL-first for shaping, filtering, aggregation, reporting.
  • Parameterized query patterns only.
  • Ensure tenant-safe data access.

6. Dynamic Menu and Routing

  • Menus are database driven.
  • Routes are generated/managed dynamically.
  • Each menu item should map to:
    • Target component mode
    • Data source or query context
    • Endpoint/service target
    • Permission contract

7. Dynamic List System

Driven by:

  • ListForm
  • ListFormFields
  • ListFormCustomization (UserUiFilter, GridState, ServerJoin, ServerWhere)
  • ListFormImport and ListFormImportLog
  • ListFormWorkflow
  • ListFormJsonRow operations

Capabilities:

  • Dynamic columns, command column, banded columns
  • Permission-aware visibility and action rendering
  • Rich filtering, sorting, grouping, paging, searching
  • Dynamic toolbar actions and URL/dialog/script command flows
  • Lookup sources:
    • StaticData
    • Query
    • WebService
  • Cascading lookup parent-child behavior
  • Dynamic validation, editor options, editor scripts (see 7.1)
  • Conditional formatting and style injection
  • Grid state save/load/reset
  • User filter save/apply/delete flows
  • Import manager and export flows (xlsx, csv, pdf)
  • SubForm integration from selected row context
  • Remote operations and dynamic datasource rebinding

Supported editor types:

  • dxAutocomplete
  • dxCalendar
  • dxCheckBox
  • dxColorBox
  • dxDateBox
  • dxDateRangeBox
  • dxDropDownBox
  • dxGridBox
  • dxHtmlEditor
  • dxLookup
  • dxNumberBox
  • dxRadioGroup
  • dxRangeSlider
  • dxSelectBox
  • dxSlider
  • dxSwitch
  • dxTagBox
  • dxTextArea
  • dxTextBox

7.1 Editor Script and Editor Options (builder-backed)

EditorScript and EditorOptions are produced from a shared vocabulary, in two places that must stay identical:

Surface Location
Visual builder (UI) ui/src/views/admin/listForm/edit/json-row-operations/editor-script/scriptRecipes.ts and .../editor-options/optionSpecs.ts + presets.ts
Seeder API (C#) api/src/Sozsoft.Platform.Domain.Shared/Editors/ — EditorScript, EditorScriptRule, EditorScriptCondition, EditorOptions, EditorOptionsBuilder

Rules AI must follow:

  • Prefer a recipe over hand-written JS. Recipes cover arithmetic (Multiply, Subtract, Percent, Sum, Formula), dates (Today, Days, Hours), data movement (Copy, SetValue, Clear, ApiToField), and view/notify actions (ReadOnly, Notify, Ask, OpenUrl). Free-form JS is Custom and is the last option.
  • Generated script carries a // @builder {...} header on the first line that stores the rules, plus // @runOnOpen when any rule runs on form open. Never edit the header by hand and never emit a script that does not match what the builder would emit — the dialog then treats the script as manually edited and closes the rule editor.
  • Rule triggers: change (default), open (default-value generation), both. Conditions join with and / or.
  • When a recipe changes on one side, change its port on the other side in the same task.
  • In seeders write EditorOptions = EditorOptions.Number(2).ShowClearButton() style expressions instead of raw JSON strings. Options marked platform: true in optionSpecs.ts deserialize into typed DTOs (GridBoxOptionsDto, TagBoxOptionsDto, ImageUploadOptionsDto); wrong types are silently ignored.

8. Dynamic Form System

  • DevExtreme Form-based runtime field generation
  • Metadata-driven item groups/tabs
  • Validation and conditional behavior
  • CRUD integration
  • Default value and runtime script handling
  • Lookup-enabled field model

9. Dynamic UI Components

Supported component families:

  • DataGrid
  • PivotGrid
  • Form
  • Chart
  • Scheduler
  • Gantt
  • TreeList / Tree view
  • SubForm tabs (List, Tree, Gantt, Scheduler, Form, Chart)
  • Widget Group (dashboard KPI cards)
  • TodoBoard — a Kanban board: columns come from statusExpr values, cards change status by drag and drop, new columns (statuses) can be added from the board

Runtime UI capabilities:

  • Per-list layout switching:
    • Grid
    • Pivot
    • Tree
    • Chart
    • Gantt
    • Scheduler
  • Per-user layout persistence
  • Lazy loading and view preloading
  • Shared dynamic datasource pipeline across layouts
  • Shared filter/search/deep-link behavior
  • Runtime refresh and query rebind
  • Runtime state lifecycle:
    • Save state
    • Load state
    • Reset state
  • Runtime import/export actions from UI flows
  • Popup and fullscreen editing scenarios
  • SubForm relation-aware context propagation and tab navigation

10. Dynamic Component Development Policy

Allowed approach:

  • Configure and bind existing dynamic component infrastructure.

Disallowed by default:

  • New custom React pages/components for normal business requirements.

If user requests custom code explicitly:

  • Provide a warning that low-code path is preferred.
  • Offer configuration-first alternative first.

10.1 Custom Component path (still not hand-written React)

When a screen genuinely cannot be expressed as a ListForm, the next step is not a physical React page. It is a Custom Component built in the Visual Designer and attached to a menu through the Wizard's Custom path.

  • The component is stored in the database (Name, RoutePath, Code, Props, Dependencies, DataSources) and compiled in the browser with @babel/standalone.
  • The designer document lives in Props.visualDesigner and in the /*__SOZSOFT_VISUAL_DESIGNER__…__*/ header of the generated code. sourceMode is visual or code; switching to code is one-way — the canvas cannot be restored afterwards, so do not propose it casually.
  • Toolbox families: layout (PageContainer, FlexRow, Spacer), data (Form — owns the four CRUD endpoints and acts as a container), platform (ListView, DataGridView, TreeView, GanttView, TodoBoard, CardView, SchedulerView, PivotView, ChartView — each embeds a ListForm screen through listFormCode), html/ui, and other custom components as custom.
  • Reuse before drawing: if the requirement is a list/tree/chart that a ListForm already serves, drop the matching platform node with its listFormCode instead of rebuilding it out of primitives.
  • Data binding goes through CRUD endpoints. Filter operators map to the CrudEndpoint GetList contract: eq is a bare query parameter, every other operator carries its name as a suffix (?Name.contains=…).
  • Permissions are two-layered and mandatory: node-level designerPermission for visibility, and per-command Form permissions (selectPermission, insertPermission, updatePermission, deletePermission). In Otomatik mode the base is the read permission the Wizard created for the component and the commands get '' / .Create / .Update / .Delete suffixes.
  • List screen permissions: App.DeveloperKit.CustomComponents{,.Create,.Update,.Delete}.
  • Every save/delete is mirrored into configs/seeds/{scope}/data/App.DeveloperKit.CustomComponents.json; the endpoints it uses are referenced through crud/{Entity}.json. A component that is not seed-backed is not done.

10.2 SQL View Designer

For shaping data before a screen binds to it, prefer a designed view over an inline query: SqlViewDesignerDialog produces T-SQL from a diagram (sources, joins, CROSS/OUTER APPLY, derived subqueries) plus an SSMS-style criteria grid (Column / Alias / Output / Group By / Sort / Filter / Or…). It is one-way — model to T-SQL. A view that does not parse back into the canonical shape drops the dialog to raw SQL mode, so hand-editing a designed view costs the designer. Aggregations available in the Group By column: GroupBy, Where, SUM, COUNT, COUNT_DISTINCT, AVG, MIN, MAX.

Persistence: only the table designer's deploy writes a seed file automatically ({sql|postgres}/object/{TableName}.sql, full CREATE script, via save-table-script). View Designer deploys and any DDL run from the SQL editor (views, procedures, functions) reach the database only — their seed files under {sql|postgres}/object/ must be written explicitly. Full mechanics and the SP/function production patterns: lowcode.instructions.md §8.1–§8.2.1 and §9.5.

11. Integrations

Notification channels:

  • Sms
  • Mail
  • Rocket
  • Desktop
  • UiActivity
  • UiToast
  • WhatsApp
  • Telegram

Sender module:

  • Email (ABP Emailing + Amazon SES)
  • SMS (ABP Sms + Posta Guvercini)
  • Rocket.Chat (HTTP API)
  • WhatsApp (HTTP API, template-based)

Notification routing model:

  • Type + Channel routing
  • Recipient targeting:
    • All
    • User
    • Role
    • OrganizationUnit
    • Custom

MailQueue:

  • Template-based body generation
  • Attachment lifecycle
  • File outputs (PDF, XLS, TXT)
  • Queue execution and logging

AI workflow integration:

  • n8n webhook chat endpoint
  • LangChain agent flow + memory window
  • Gemini chat model connector

12. Background Processing

Supported engines:

  • Hangfire
  • ABP Background Workers

Typical use cases:

  • Scheduled SQL execution
  • Notification dispatching
  • Email and integration automation

13. Security and Compliance Rules

  • Enforce RBAC and permission-driven visibility at all layers.
  • Always include permission definitions in feature design.
  • Never output real credentials, tokens, keys, or secrets.
  • Use placeholders in examples.
  • Maintain tenant isolation in every query and action.

14. Required AI Output Contract

For each implementation proposal, AI output must include:

  1. Goal
  2. Decision flow result (which step used)
  3. Artifacts to configure
  4. SQL/query/endpoint design (if needed)
  5. Menu + route + component mapping
  6. Permission and role mapping
  7. Tenant isolation notes
  8. Validation and test checklist
  9. Rollback strategy

15. Quality Gate Checklist

Before finalizing any answer, verify all:

  • No unnecessary custom code suggestion
  • No forbidden React component proposal
  • Tenant awareness is explicit
  • Permission strategy is explicit
  • Menu-route binding is explicit
  • Data safety and SQL parameterization considered
  • Background processing considered when async/scheduled

16. Anti-Patterns (Do Not Suggest)

  • Writing controllers for flows already covered by dynamic infrastructure
  • Hardcoded endpoint mapping without permission model
  • Static UI screens disconnected from list/menu/route model
  • Direct non-tenant-safe query patterns
  • Copying secrets into examples

17. Example Request Types AI Must Handle

  • Create customer list screen
  • Build purchase module
  • Create dashboard with charts
  • Generate reporting screen
  • Add approval workflow
  • Add integration-triggered notification process

18. Escalation Strategy

When configuration cannot satisfy requirement:

  1. Try SQL-based design
  2. Try Custom Endpoint
  3. Try Dynamic Service
  4. Propose minimal code change with explicit justification — this step is out of frame: ask and wait for approval before touching code (rule 3.6).

19. Final Rule

This platform is not a traditional code-first app.

It is a runtime configurable low-code engine.

AI must optimize for platform consistency, configurability, auditability, and safe scale.

20. Request Classification Matrix

Before proposing any solution, classify the request into one of these classes:

Class A - Pure configuration:

  • Menu, route, list/form fields, validation, permissions, layout, filters
  • Expected output: configuration-first plan only

Class B - Configuration + SQL:

  • Reporting, complex filtering, aggregation, lookup dependencies
  • Expected output: configuration + SQL + endpoint mapping

Class C - Configuration + Integration:

  • Notification, sender, queue, webhook, workflow automation
  • Expected output: configuration + integration contract + retry/fallback notes

Class D - Escalated code path:

  • Only when A/B/C cannot satisfy requirement
  • Expected output: explicit justification, minimal scope code plan, rollback plan

21. Response Playbooks

21.1 New Screen Playbook

  1. Define business objective and actor roles.
  2. Define ListForm and ListFormFields structure.
  3. Define menu entry and route mapping.
  4. Define permissions (R/C/U/D/E) and role mapping.
  5. Define datasource and query strategy.
  6. Define runtime filters, lookup, validations.
  7. Define import/export and state requirements.
  8. Define acceptance checklist.

21.2 Workflow/Approval Playbook

  1. Define states and transition rules.
  2. Define transition permissions by role.
  3. Define transition side-effects (notification, queue, endpoint call).
  4. Define audit log and failure handling.
  5. Define rollback/compensation behavior.

21.3 Report/Dashboard Playbook

  1. Define KPIs and dimensions.
  2. Define SQL shaping and aggregation logic.
  3. Define chart/pivot configuration.
  4. Define date/tenant filters.
  5. Define export needs and performance constraints.

22. Mandatory Acceptance Criteria Template

Every final proposal must include a clear, testable acceptance list:

  1. Feature can be enabled via configuration.
  2. Tenant boundaries are preserved.
  3. Required permissions block unauthorized access.
  4. Menu-route-screen path is navigable.
  5. Data operations are parameterized and safe.
  6. Runtime filters and state behaviors work.
  7. Integration events (if any) are observable and retry-safe.
  8. No unnecessary custom code introduced.

23. AI Output Templates

23.1 Configuration-only Output Template

  1. Goal
  2. Configuration artifacts
  3. Menu/route mapping
  4. Permission mapping
  5. Validation checklist

23.2 Configuration + SQL Output Template

  1. Goal
  2. Required configuration artifacts
  3. SQL design (inputs, outputs, filter parameters)
  4. Endpoint/service mapping
  5. Security and tenant notes
  6. Validation checklist

23.3 Escalated Code Output Template

  1. Why configuration is insufficient
  2. Minimal code scope
  3. Compatibility with existing dynamic architecture
  4. Migration and rollback plan
  5. Risk and test plan

24. Performance and Scalability Rules

  • Prefer server-side filtering/sorting/paging for large datasets.
  • Avoid unbounded result sets in dynamic queries.
  • Use indexing-aware query patterns for reporting screens.
  • Keep chart/pivot queries aggregation-focused.
  • Separate interactive screen queries from heavy export queries.
  • Use background jobs for long-running batch operations.

25. Observability and Audit Rules

  • Log key operations at list/form/integration boundaries.
  • Preserve who/when/what audit metadata for critical changes.
  • Capture integration failures with retry reason and payload context.
  • Keep user-facing messages simple, logs detailed.
  • Ensure state changes are diagnosable for support teams.

26. Error Handling Policy

  • Never expose raw secrets or internal stack details to end users.
  • Return actionable, localized, user-level messages.
  • Keep technical diagnostics in logs.
  • For integration failures:
    • Retry where safe
    • Record dead-letter/failure state
    • Provide manual replay strategy when needed

27. Change Management Policy

  • Prefer additive changes over breaking modifications.
  • Keep existing ListForm contracts backward compatible where possible.
  • Document behavior changes in rollout notes.
  • For destructive changes, require explicit migration path.

28. Definition of Done for AI Proposals

A proposal is complete only if all are present:

  1. Decision flow step selected and justified.
  2. Configuration artifacts clearly listed.
  3. Permission and tenant design included.
  4. Menu-route-component mapping included.
  5. Validation checklist included.
  6. Risk/rollback notes included.

29. Prohibited Suggestion Set

AI must not suggest:

  • Quick custom React page as first solution
  • Hardcoded tenant ids or environment secrets
  • Direct SQL string concatenation with user input
  • Endpoint exposure without permission definitions
  • Bypassing platform menu-route model for business screens

30. Final Governance Statement

This manual is authoritative for AI behavior in this repository.

When in doubt, AI must choose the path that preserves:

  • Low-code configurability
  • Tenant safety
  • Permission correctness
  • Operational auditability
  • Long-term maintainability

31. Seeder-Driven Low-Code Development Guide (Authoritative)

There are two seed surfaces. AI must not mix them.

A. Repository seeds (shipped with code) — api/src/Sozsoft.Platform.DbMigrator/Migrations/. Platform-owned screens, menus, permissions and language texts. Changing them requires a build and a deploy. AI must learn and teach implementation flow primarily from these assets:

  • ListFormSeeder_Saas.cs / ListFormSeeder_Administration.cs / ListFormSeeder_{Modul}.cs
  • MenusData.json
  • PermissionsData.json
  • HostData.json
  • LanguagesData.json
  • WizardDataSeeder.cs / CrudDataSeeder.cs — the seeders that read surface B below

B. Runtime seeds (written by the running application) — configs/seeds/, resolved through SeedPathResolver. The Wizard, the Custom Components screen / Visual Designer and the CRUD Endpoint Manager write here; the seeders above restore them when the database is recreated. Scope folders mirror the CDN layout:

configs/seeds/host/{wizard,data,crud,sql/{object,execute},postgres/{object,execute}}
configs/seeds/tenants/{tenantId}/…            same layout, tenant scope
configs/seeds/.imports/{importId}/…           wizard import staging + backup (not scanned)

Rule: anything produced at runtime must land in surface B. A feature that disappears when the database is recreated is not delivered.

If user asks "how to add a new module/screen", AI must answer with this exact operational sequence.

31.1 Step 1 - Create ListForm definition

Define a new ListForm with at least:

  • ListFormCode, Name, Title
  • DataSourceCode
  • SelectCommandType + SelectCommand
  • KeyFieldName + KeyFieldDbSourceType
  • PermissionJson (create/read/update/delete/export/import/note)
  • EditingOptionJson + EditingFormJson
  • FilterRowJson, HeaderFilterJson, SearchPanelJson, GroupPanelJson
  • SelectionJson, ColumnOptionJson, PagerOptionJson
  • InsertServiceAddress, UpdateServiceAddress, DeleteCommand

For parent-child scenarios, define SubFormsJson relation mapping (ParentFieldName -> ChildFieldName, DbType).

31.2 Step 2 - Create ListFormFields

For each field, define runtime behavior through ListFormField records:

  • Data binding: field name, db type, source
  • UI behavior: visibility, order, width, grouping, fixed/band settings
  • Editing behavior: editor type (dxTextBox, dxSelectBox, dxNumberBox, etc.), required, options
  • Lookup behavior: data source type, display/value members, cascade rules
  • Validation rules and default values
  • Command/action columns where needed

AI must prioritize metadata-based field behavior instead of suggesting custom React forms.

31.3 Step 3 - Add menu and route mapping

From MenusData.json patterns, AI must define both:

  • Routes entry:
    • key, path, componentPath, routeType, authority
  • Menus entry:
    • ParentCode, Code, DisplayName, Url, Icon, RequiredPermissionName, Order

For dynamic list screens, base route pattern is:

  • /admin/list/{ListFormCode}

AI must ensure menu URL and route path point to same screen contract.

31.4 Step 4 - Add permissions

From PermissionsData.json patterns, AI must define:

  • Permission group (if missing)
  • Permission definitions for feature root and actions
  • Menu permission binding (RequiredPermissionName)

Minimum action set suggestion:

  • .Default
  • .Create
  • .Update
  • .Delete
  • .Export
  • .Import
  • .Note

AI must never propose menu/route without permission contract.

31.5 Step 5 - Add settings/integration dependencies

From HostData.json patterns, AI must define required settings when feature depends on external services:

  • Sender credentials and endpoints (sms/mail/whatsapp/rocket)
  • AiBot integration endpoint and activation state
  • Feature-specific setting keys, providers, encryption flags

If integration required and setting missing, AI must explicitly add "blocking prerequisite" note.

31.6 Step 6 - Data and service contract

AI must produce one of:

  • Direct table/view select command
  • Parameterized SQL via managed query
  • Custom endpoint / dynamic service

AI must include tenant-safe filters and avoid string concatenation.

31.7 Step 7 - Delivery checklist

For every new low-code feature, AI output must list:

  1. New ListForm code and purpose
  2. ListFormField set (critical columns/editors/lookups)
  3. Route record
  4. Menu record
  5. Permission records
  6. Required settings/integrations
  7. Validation and rollback notes

If this 7-item list is incomplete, proposal is not accepted.

31.8 AI response style for implementation requests

When user asks for a screen/module, AI must answer in this order:

  1. Decision flow class (A/B/C/D)
  2. Seeder-style artifacts to add (ListForm, Fields, Menu, Route, Permission, Setting)
  3. If needed, SQL/endpoint contract
  4. Test and rollback checklist

AI should produce practical, copy-adaptable artifact definitions and avoid abstract-only explanations.

31.9 Screen brief, discovery questions and image-based requests

A request arrives either as prose or as a screenshot / mockup / photo of the desired screen. Both enter the same pipeline — and for a new screen/component the pipeline starts with questions, not files:

  1. Run the discovery round (lowcode.instructions.md §0.6). Ask in batches (max 4 questions per round, each with 2–4 options and a recommended default), max three rounds. Round 1 always covers: screen kind (List/Wizard vs Custom Component vs single-record form), data source, owning module, and tenancy scope. Round 2 uses the path-specific question set (§0.6.3 for List, §0.6.4 for Custom). Never ask what the repo already answers — search first, confirm findings instead of re-asking. If the user says "you decide / don't ask", skip the round and build on defaults.
  2. Turn the answers into a single screen brief — purpose, data source, columns and editors, layouts, actions, sub-screens, widgets, approval flow, menu, permissions, tenancy, language texts. For an image, read it first (page regions → main region type → toolbar → columns → filters → form controls → row actions); the image answers most of round 2, so ask only what an image cannot show (§0.7.4).
  3. Get the brief confirmed before writing any seed file. Mark defaulted lines (varsayılan) so the user sees what they are approving.
  4. Pick the tool: grid-shaped work → SQL Query Manager + Wizard; free layout / dashboard / single-record custom form → Custom Component. When in doubt, recommend the Wizard.
  5. Produce the seed files in dependency order, then list them and restate the defaulted choices.

An image is a reference, not a pixel contract: build the closest thing the platform's own components give, and state at the end what had no equivalent. Three things are never assumed, always asked: which table is written to, who approves (when there is an approval flow), and the formula of any calculation/business rule. This question-first rule applies only to producing a new screen/component; fixes, field additions, debugging and explanations proceed directly.

The concrete question sets, brief template, the image-element → artifact mapping and the visual-control → EditorType mapping are in lowcode.instructions.md §0.6–§0.7.

32. Mandatory Default Behaviors (Do Not Ask Repeatedly)

The following defaults are mandatory unless user explicitly overrides them.

32.1 SQL Table Designer default column behavior

When user requests creating a table and only specifies business columns (for example FullName, Phone), AI must still ensure platform-standard technical columns are included by default in SQL Query Manager table design flow:

  • TenantId (multi-tenant compatibility)
  • Full audited set:
    • Id
    • CreationTime
    • CreatorId
    • LastModificationTime
    • LastModifierId
    • IsDeleted
    • DeletionTime
    • DeleterId

Rules:

  • Do not require user to explicitly request these columns each time.
  • If user explicitly says "no tenant" or "no audit", then respect that override.
  • Primary key strategy must remain compatible with existing index/key policy.

32.2 Wizard menu parent fallback behavior

When creating menu via Wizard/ListForm and user does not explicitly specify parent menu:

  • Do not auto-place under Definitions by default.
  • Create (or use) a dedicated new top-level parent menu for that feature/module.
  • Assign top-level menu Order as next available order (max(Order) + 1) among root menus.
  • Place the generated list/menu item under this newly created parent.

Rules:

  • Definitions can be used only when user explicitly selects it.
  • Permission contract must be created/bound for both parent and child menu items.
  • Route/menu consistency remains mandatory (Url and screen contract must match).

32.3 Wizard component kind and menu creation

ListFormWizardDto.ComponentKind is the wizard's fork and the first field in the seed file. Default is List, so older seed files that lack it keep working.

Kind Produces Menu URL Child permissions
List ListForm + ListFormFields + Route + Menu + Permissions + language keys /admin/list/{ListFormCode} .Create, .Update, .Delete, .Export, .Import, .Note
Custom Menu + Permissions + language keys; the screen is the selected Custom Component the component's RoutePath .Create, .Update, .Delete only

Export / Import / Note exist only in the ListForm ecosystem. Never propose them on the Custom path.

CreateMenu = false (menu-less wizard): no menu record — and no parent menu record — is created; ListForm, permissions and language keys are still produced. Use it when the screen is meant to be embedded elsewhere as a SubGrid/part. Default is true.

32.4 Permission group selection

The wizard's permission group comes from a select list backed by GetWizardPermissionGroups. Display names are read from the language key whose name equals the group name.

  • Selecting an existing group fills PermissionGroupEn/Tr (seed file: Language.PermissionGroupEn/Tr); if left blank the server writes the database values back, so the seed file always carries both languages.
  • Defining a new group writes those texts to the language key with the same name as the group.
  • AI must never propose a permission group without EN + TR display names.

32.5 Wizard export/import is a package, not a file

Exporting a wizard produces a zip whose paths are relative to the scope folder (host / tenants/{tenantId}) and which carries every dependency:

  • wizard/{file}.json
  • data/App.DeveloperKit.CustomComponents.json — Custom path; the file is filtered down to the exported component and its dependency chain, never exported whole
  • crud/{entity}.json — endpoints those components use
  • {sql|postgres}/{object|execute}/{object}.sql — the object behind SelectCommand on the List path

Import is two-phase: AnalyzeImport (unzip to .imports/{id}/staged, classify each entry as New / Identical / Conflict, conflicts resolved in a diff editor) then ApplyImport (file-by-file write, previous content backed up so RollbackImport can undo the whole batch), closed by CompleteImport.

A data/*.json entry is compared and merged by row, not by file: the diff shows only the rows whose keys the archive carries (file-level GeneratedAt/Order are excluded), so unrelated records never surface as a difference — no matching row means New (insert), a matching identical row means Identical (nothing is transferred), a matching different row means Conflict (update). The file itself is never overwritten: rows are merged into the target by key (incoming row wins, target-only rows are kept). CompleteImport then applies exactly the data/ files it wrote to the database through IListFormSeedDataApplier with overwriteExisting: true — a missing row is inserted, an existing one is updated from the file (unlike migrate/seed, where a possibly stale file must not overwrite live data), and a row that was soft deleted is revived by clearing the columns the screen's DeleteCommand sets (IsDeleted/DeletionTime/DeleterId), otherwise the default filter would keep hiding it — and reports the inserted/updated/skipped counts. Data files that were already identical to the target are applied too: there was nothing to write, but the rows may be missing or soft deleted in the database. A file the user chose to keep (different, not written) is left alone. This step is not covered by RollbackImport, which only restores files and must be run before it. The other folders (wizard, crud, sql) stay as files and reach the database through the seeders or a wizard deploy.

Limits: allowed root folders wizard, crud, data, sql, postgres (and only object / execute under the SQL provider folders); 5 MB per entry, 50 MB per archive, 500 entries. Permissions: App.Listforms.Wizard.Export / .Import.

AI must not propose moving a screen between environments by copying a single json file.

32.6 AI enforcement requirement

AI must proactively apply these defaults in:

  • implementation proposals,
  • code/seed changes,
  • migration and wizard behavior recommendations.

If AI output omits these defaults without explicit user override, output is non-compliant.