Tutorial: build a task-management module

Documentation status: tutorial — see Maturity and evidence.

Goal

Build a first complete business module using current logiCells conventions: package, manifest, Task model, conceptual and persistence facets, then activation in an application configuration.

This tutorial uses YAML as the primary path. The same structure can be expressed in XML when a project chooses that route; both formats target the same Runtime contract.

Target structure

TaskManagement/
├── packages/
│   └── TaskManagement.package.yaml
└── meta/
    └── models/
        └── TaskManagement/
            ├── ClassItems.manifest.yaml
            ├── Task.model.yaml
            ├── Project.model.yaml
            └── TaskBelongsToProject.model.yaml

Naming conventions

• ClassItems is a manifest, not a business model.
• Business models use *.model.yaml or *.model.xml.
• The concrete format is visible in the extension.
• Application identifiers use a project-owned prefix. This tutorial uses tsk#.

1. Create the package

package:
  name: TaskManagement
  enabled: true

The package defines the module loading boundary. Keep it minimal until the first model has been validated.

2. Create the class manifest

ClassItems.manifest.yaml:

classes:
  - class:
      classId: tsk#task
      name: Task
      type: entity
  - class:
      classId: tsk#project
      name: Project
      type: entity
  - class:
      classId: tsk#task_belongs_to_project
      name: TaskBelongsToProject
      type: relation

A classId is a stable conceptual identity. Do not change it casually once data, relations, services, or integrations depend on it.

3. Declare Task

Task.model.yaml:

class:
  classId: tsk#task
  name: Task
  type: entity
  concepts:
    - concept:
        name: Entity
        facets:
          - facet:
              type: hypergraph
              name: main
              fields:
                - Name: String
                - Description: String
                - Priority: Integer
                - StartDate: DateTime
                - EndDate:
                    type: DateTime
                    nullable: true

This first model establishes the conceptual meaning of Task. Do not start with storage: validate the model and loading path first.

4. Add the persistence projection

Once the conceptual model is stable, add a persistence facet supported by your Runtime contract:

facets:
  - facet:
      type: database
      name: Task
      mappingTableName: lgcTask
      fields:
        - IdTask:
            type: String
            size: 32
            rolePath: Id
        - ClassIdTask:
            type: String
            size: 32
            defaultValue: tsk#task
            rolePath: ClassId
        - Name:
            type: String
            size: 120
        - Description:
            type: String
            size: 500
        - Priority: Integer
        - StartDate: DateTime
        - EndDate:
            type: DateTime
            nullable: true

The persistence facet is a technical projection. Business meaning remains in the conceptual model.

5. Declare Project

class:
  classId: tsk#project
  name: Project
  type: entity
  concepts:
    - concept:
        name: Entity
        facets:
          - facet:
              type: hypergraph
              name: main
              fields:
                - Name: String
                - Description: String

6. Relate Task and Project

The relationship is a model element, not merely a technical foreign key.

class:
  classId: tsk#task_belongs_to_project
  name: TaskBelongsToProject
  type: relation

Complete participants and constraints using the forms supported by your Runtime version. Preserve relation identity in the conceptual model even when a relational database projection also exists.

7. Activate the module

Add the package to the application configuration used for testing. Deployment paths belong in configuration; they should not be hard-coded into the business model.

On first startup, verify in this order:

1. application configuration;
2. package;
3. manifest;
4. Task class;
5. facets;
6. relation;
7. persistence;
8. views and services only afterwards.

This boundary-inward diagnostic order avoids debugging a view when the model itself never loaded.

8. Verify first success

The first success is not yet a complete application. Confirm that:

• the package loads;
• classId values are unique and resolved;
• Task and Project are available;
• the relation is recognized;
• the configuration selects the intended Runtime mode.

9. Next step

Continue with Build the module views, then add services only after the model and views are stable.