Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 52 additions & 77 deletions AGENTS.md

Large diffs are not rendered by default.

8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,12 @@ PM_SKILLS_PROFILE=migration NAYRA_SERVER=https://pm.example.com PM_SYNC_TOKEN=
```

## Development
If you need to create a new ProcessMaker package run the following commands:
Prefer `composer create-project` above. To rename a local clone:

```
git clone https://github.com/ProcessMaker/package-skeleton.git
cd package-skeleton
php rename-project.php package-skeleton
git clone https://github.com/ProcessMaker/package-skeleton.git my-package
cd my-package
php rename-project.php my-package
composer install
npm install
npm run dev
Expand Down
11 changes: 6 additions & 5 deletions ai-docs/best-code-practices.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Best code practices

Cross-project coding standards for package-plg. Prefer these when writing or refactoring code so SonarQube and review stay green.
Cross-project coding standards for Package Skeleton (and packages created from it). Prefer these when writing or refactoring code so SonarQube and review stay green.

**SOLID:** On every frontend and backend implementation, apply SOLID. Agent skill: [`.cursor/skills/apply-solid/SKILL.md`](../.cursor/skills/apply-solid/SKILL.md).
**SOLID:** On every frontend and backend implementation, apply SOLID (single responsibility, open/closed, Liskov, interface segregation, dependency inversion).

## Sonar review (required)

Expand All @@ -21,7 +21,7 @@ Keep each function/method at cognitive complexity ≤ 15. When a method approach

## Use at most 3 returns in a function

Functions should not contain too many return statements
Functions should not contain too many return statements.

## Class size

Expand All @@ -38,9 +38,10 @@ Prefer optional chain expressions (`?.`) over nested null/undefined checks. They

## Related to code

- Do not use unnecessary use of boolean literals in conditional expression. e.g. `condition ? true : false` when `condition` is already a boolean.
- [S7744] Do not use unnecessary fallback objects should not be used when spreading in object literals.
- Do not use unnecessary boolean literals in conditional expressions, e.g. `condition ? true : false` when `condition` is already a boolean.
- [S7744] Do not use unnecessary fallback objects when spreading in object literals.

## Related to Vue components

- Declare emits array for all emitted events.
- Declare the props as object that include type of the properties.
2 changes: 1 addition & 1 deletion ai-docs/credit-deal-coverage.html
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ <h2>Implemented, and still needs a manual check</h2>
</table>

<h2>Publication</h2>
<p>On 10 November 2026 the versioned assets were created on https://tce-eng.dev.cloud.processmaker.net: scripts 227–242, screens 433–489, process credit-deal-notification (83), and process credit-deal-process (84). Publication does not change the percentages above. The package classes, the Vue bundle, the acd_* migration, and the seed data were not installed with those assets, so a case still cannot run end to end. The Send Email task’s pm:config screenRef was stored as the named reference ${screen:credit-deal-notification-email}; the connector reads that JSON, so screen 464 still has to be selected on the task.</p>
<p>On 10 November 2026 the versioned assets were published to the PM4 instance set in package <code>.env</code> as <code>PM_BASE_URL</code> (configured at <code>composer create-project</code>): scripts 227–242, screens 433–489, process credit-deal-notification (83), and process credit-deal-process (84). Publication does not change the percentages above. The package classes, the Vue bundle, the acd_* migration, and the seed data were not installed with those assets, so a case still cannot run end to end. The Send Email task’s pm:config screenRef was stored as the named reference ${screen:credit-deal-notification-email}; the connector reads that JSON, so screen 464 still has to be selected on the task.</p>

<footer>Credit Deal coverage report. Inventory of 358 PM3 assets. 317 resolved (88%), 41 open. Functionality 83% on the closing path and 66% including generated documents and the dashboard.</footer>
</body>
Expand Down
332 changes: 30 additions & 302 deletions ai-docs/custom-vue-components.md

Large diffs are not rendered by default.

73 changes: 31 additions & 42 deletions ai-docs/hexagonal.md
Original file line number Diff line number Diff line change
@@ -1,28 +1,30 @@
# Hexagonal layout for TCE domains
# Hexagonal layout for project domains

Military today is a transitional design: `src/Military/*Actions.php` plus RedBean (`Military\DB`) and a small `app()` container because **script tasks cannot use Laravel**. New domains keep that runtime constraint but live under `src/Projects/{Pascal}/` with namespace `ProcessMaker\Package\PackagePlg\Projects\{Pascal}`. Do not add new hexagons next to `src/Military/`.
Domains live under `src/Projects/{Pascal}/` with namespace `ProcessMaker\Package\PackageSkeleton\Projects\{Pascal}`. After `rename-project.php`, `PackageSkeleton` becomes the package Pascal name. This layout matches full domain packages built on ProcessMaker; the skeleton ships empty folders and shared `Model` only — no dependency on another composer package.

Script tasks cannot use Laravel; keep that runtime constraint.

## Layers

| Layer | Allowed to depend on | Role |
|---------------------|-----------------------------------------------|-----------------------------------------------------|
| Domain | Shared `Model` only (plus nothing else outside Domain) | Entities extending `Projects\Shared\Domain\Model`, VOs, ports, JSON Schemas |
| Application | Domain | Use cases; orchestrate ports; shape process `$data` |
| Infrastructure | Domain, Application, RedBean, PM helpers | Persist, match SQL, PM container |
| Layer | Allowed to depend on | Role |
|----------------|-----------------------------------------------------------|---------------------------------------------------------------------|
| Domain | Shared `Model` only (plus nothing else outside Domain) | Entities extending `Projects\Shared\Domain\Model`, VOs, ports, schemas |
| Application | Domain | Use cases; orchestrate ports; shape process `$data` |
| Infrastructure | Domain, Application, RedBean/HTTP helpers | Persist and external I/O adapters |

## Script-task rules

- No Laravel service container, no Eloquent, no facades.
- Script Tasks can return the data that could be updated.
- Script tasks return the process data that should be updated.

## Use case shape

No port when the script only maps `$data` (no DB/HTTP):

```php
namespace ProcessMaker\Package\PackagePlg\Projects\{Pascal}\Application\UseCases;
namespace ProcessMaker\Package\PackageSkeleton\Projects\{Pascal}\Application\UseCases;

final class MapTranscriptFormData
final class MapFormData
{
/**
* Shape process $data for the script task. No I/O.
Expand All @@ -40,12 +42,12 @@ final class MapTranscriptFormData
Port only when there is DB/HTTP. Constructor-inject a Domain port; adapter lives in Infrastructure:

```php
namespace ProcessMaker\Package\PackagePlg\Projects\{Pascal}\Application\UseCases;
namespace ProcessMaker\Package\PackageSkeleton\Projects\{Pascal}\Application\UseCases;

final class ExecuteTranscriptActions
final class SaveRecord
{
public function __construct(
private TranscriptRepository $transcripts,
private RecordRepository $records,
) {}

public function handle(array $data): array
Expand All @@ -54,51 +56,38 @@ final class ExecuteTranscriptActions
}
}
```

## Ports vs Eloquent

- `src/Models/{Pascal}`: Laravel HTTP, migrations, factories.
- Domain\Ports + RedBean adapters: script tasks and any code that must run inside the PM script executor.
- SQL from the executor: bound parameters and backtick identifiers (`groups`, `status`, `rank`, …). Unquoted reserved words → MySQL 1064.
- Domain\Ports + adapters: script tasks and any code that must run inside the PM script executor.
- Do not call Eloquent models from Application use cases invoked from scripts.

Do not call Eloquent models from Application use cases if those use cases are invoked from scripts.

JSON Schema files live in `src/Projects/{Pascal}/Domain/Schemas/`. Details and rejected locations: [models.md](models.md).
JSON Schema files live in `src/Projects/{Pascal}/Domain/Schemas/`. Details: [models.md](models.md).

## Reuse (script tasks)

Search `src/Projects/` (especially `Shared/`), `src/Military/`, and `src/Services/` **before** adding a class or method. Call what exists. If two use cases would copy the same I/O (collection PATCH, student SIS lookup, RedBean query helper), extract a **narrow Shared port** + Infrastructure adapter and inject it. Do not add a god `ScriptService` / `Utils`. Do not add Shared ports that are not in the tree yet.
Search `src/Projects/` (especially `Shared/`) **before** adding a class or method. If two use cases would copy the same I/O, extract a **narrow Shared port** + Infrastructure adapter and inject it. Do not add a god `ScriptService` / `Utils`. Do not add Shared ports that are not in the tree yet.

`app(Foo::class)` is the project `ScriptTaskContainer` (not Laravel), and only if that domain already has it. Default: wrapper `isset` fake + `new UseCase($adapter)` or `new UseCase()`. It does not load classes missing from the Nayra image. After adding `src/` classes used from a script, rebuild the php-nayra executor.
Default wiring: wrapper `isset` fake + `new UseCase($adapter)` or `new UseCase()`. After adding `src/` classes used from a script, rebuild the php-nayra executor.

### Naming and documentation

Names: verb + object (`SaveInCollectionV3`, `patchApplicationRecord`). Not `Helper`, `Processor`, `Manager`, `do`, `run`.

Variables: camelCase English words for the **value**. `$institutionId`, `$evaluateRow`, `$coursePair`, `$processMakerUserId`. Not APV3 letters (`$x`, `$c`, `$rev`) or cryptic abbrevs (`$instCode`, `$userIdPm`, `$sides`, `$art`, `$his`). Maps: `$courseIdByInternalSubject`, not `$map`.
Names: verb + object (`SaveRecord`, `PatchApplication`). Not `Helper`, `Processor`, `Manager`, `do`, `run`.

Process `$data` keys and DB columns stay exact (`OKCourses`, `compount_id`). Locals can be clear, then copy into those keys.
Variables: camelCase English words for the **value**. `$institutionId`, `$evaluateRow`. Not cryptic abbrevs (`$instCode`, `$x`).

Every public class and public/protected method: English docblock that states **what**, **when to call**, **what not to do**, then `@param` / `@return`. The next refactor should reuse from that text instead of duplicating.

## Example Mapping Military → hexagonal

| Military file | New place (`src/Projects/{Pascal}/...`) |
|------------------------------------------|-------------------------------------------------------|
| `src/Military/JoinTranscriptsAction.php` | `Application/UseCases/JoinTranscripts.php` |
| `src/Military/ExecuteDataActions.php` | `Application/UseCases/ExecuteDataActions.php` |
| `src/Military/DB.php` | `Infrastructure/Persistence/RedBeanConnection.php` |
| `src/Models/Military/*Model.php` | `Domain/Entities/*.php` extending Shared `Model` |
| `src/Models/Military/Schemas/*.schema.json` | `Domain/Schemas/*.schema.json` |
Process `$data` keys and DB columns stay exact. Locals can be clear, then copy into those keys.

Every public class and public/protected method: English docblock with **what**, **when to call**, **what not to do**, then `@param` / `@return`.

## UseCases for User Screens

Before to create or migrate a screen use case ask the following to the developer:

Input: Screen Name defined in processmaker
Input: Use Cases of the screen
Input: Actor
Input: Description of the screen
Before creating or migrating a screen use case, ask:

Based on this information create or modify the php services, entities, schemas, also the resources like css, js and yaml in the right place. Screen YAML + Vue: [SKILL.md](SKILL.md) §4. Shared Vue catalog: `ai-docs/military/architecture/frontend.md`.
- Screen name defined in ProcessMaker
- Use cases of the screen
- Actor
- Description of the screen

Then create or modify PHP services, entities, schemas, and resources (CSS, JS, YAML) in the right place per root [AGENTS.md](../AGENTS.md).
21 changes: 21 additions & 0 deletions ai-docs/models.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Domain models

Domain entities live under `src/Projects/{Pascal}/Domain/Entities/` and must extend:

`ProcessMaker\Package\PackageSkeleton\Projects\Shared\Domain\Model`

After `rename-project.php`, `PackageSkeleton` becomes the package Pascal name (e.g. `PackageMyApp`).

## Rules

- Not Eloquent. Hydrate from process `$data` arrays; serialize back with `jsonSerialize()`.
- Implement `schemaPath()` returning an absolute path to `Domain/Schemas/{entity}.schema.json`, or `''` to skip validation until the schema exists.
- Validation uses `ValidatesWithJsonSchema` and `swaggest/json-schema` (declared in this package `composer.json`).
- Do not put schemas under `src/Models/{Pascal}/Schemas/`.
- Do not invent a project-local `*Model` base class.

## First entity

1. Add `src/Projects/{Pascal}/Domain/Schemas/{entity}.schema.json`.
2. Add `Domain/Entities/{Entity}.php` with `public static function schemaPath(): string`.
3. Keep HTTP/Eloquent models in `src/Models/{Pascal}` separate from domain entities.
6 changes: 3 additions & 3 deletions ai-docs/report.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ description: >-

# Asset coverage report

Write it in English when either piece of work finishes. One current PDF per domain: overwrite `ai-docs/{slug}/{slug}-coverage.html` and the PDF. Credit Deal is the layout sample, not a source of numbers: [credit-deal-coverage.html](../../../ai-docs/credit-deal-coverage.html).
Write it in English when either piece of work finishes. One current PDF per domain: overwrite `ai-docs/{slug}/{slug}-coverage.html` and the PDF. Credit Deal is the layout sample, not a source of numbers: [credit-deal-coverage.html](./credit-deal-coverage.html).

## Outputs

Expand Down Expand Up @@ -87,9 +87,9 @@ Closing-path percent = points of the seven "yes" rows / 80. Full percent = point
6. Open items. Every row names the asset, the count, and why it was not implemented.
7. Dropped on purpose, with why.
8. Implemented work that still needs a manual check (engine walkthrough, visual diff of SQL screens, empty group ids, generated email attachments).
9. Publication. If nothing was published, say so. If it was, list process, screen, and script ids and what the publish did not install (package classes, Vue bundle, migration, seeds).
9. Publication. If nothing was published, say so. If it was, list process, screen, and script ids and what the publish did not install (package classes, Vue bundle, migration, seeds). Name the target only via `PM_BASE_URL` from the package `.env` (wizard at create-project), or “the configured PM4 instance”. Do not hardcode tenant hostnames (for example `*.dev.cloud.processmaker.net`).

No secrets, tokens, or personal emails.
No secrets, API tokens, or personal emails. Do not paste full `PM_BASE_URL` values in reports unless the user asked for a host-specific handoff.

## PDF

Expand Down
19 changes: 10 additions & 9 deletions ai-docs/structure.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# TCE project folder structure
# Project folder structure

Canonical layout for a new domain `{slug}` / `{Pascal}` / table prefix `{prefix}`.

Expand All @@ -13,7 +13,7 @@ ai-docs/{slug}/
└── frontend.md # Vue screens and shared components used
```

Mirror High School: a dedicated `ai-docs/{slug}/` tree, not a single mega-file. Index every new architecture doc from `AGENTS.md`.
Use a dedicated `ai-docs/{slug}/` tree, not a single mega-file. Index every new architecture doc from that domain `AGENTS.md`.

Root `AGENTS.md` must link `./ai-docs/{slug}/AGENTS.md`.

Expand All @@ -22,7 +22,7 @@ Root `AGENTS.md` must link `./ai-docs/{slug}/AGENTS.md`.
```
projects/{slug}/
├── bpmn/
│ └── {slug}-process.bpmn # omit if not in scope
│ └── {slug}-{purpose}.xml
├── scripts/
│ ├── {slug}-script-name.php
│ └── {slug}-other-script.php
Expand All @@ -33,13 +33,14 @@ projects/{slug}/

## PHP (hexagonal)

Namespace: `ProcessMaker\Package\PackageName\Projects\{Pascal}\...`
Namespace: `ProcessMaker\Package\PackageSkeleton\Projects\{Pascal}\...` (renamed with the package).

```
src/Projects/Shared/Domain/Model.php # JsonSerializable + ValidatesWithJsonSchema (always)
src/Projects/Shared/Domain/Model.php # JsonSerializable + optional JSON Schema validation
src/Traits/ValidatesWithJsonSchema.php
src/Projects/Shared/Domain/Ports/ # only after a second domain copies the same I/O
src/Projects/Shared/Infrastructure/ # adapters for those Shared ports
src/Projects/Shared/Application/UseCases/ # APP scripts shared across two+ domains
src/Projects/Shared/Application/UseCases/ # scripts shared across two+ domains

src/Projects/{Pascal}/
├── Domain/
Expand All @@ -61,7 +62,7 @@ database/migrations/ # {prefix}_* tables

```
resources/js/projects/{slug}/
├── shared/ # domain CAT2 only if reused by 2+ screens
├── shared/ # domain-shared only if reused by 2+ screens
└── {screenFolder}/
├── {ScreenName}.vue
├── {ScreenName}.stories.js # title: Projects/{Pascal}/...
Expand All @@ -71,7 +72,7 @@ resources/js/projects/{slug}/
└── config/
```

Shared CAT1: `resources/js/projects/shared/`. Dashboards that are not domain-specific stay in `resources/js/dashboards/`.
Package-wide shared UI: `resources/js/projects/shared/`.

## Tests

Expand All @@ -84,5 +85,5 @@ tests/Feature/ # HTTP only
Run:

```bash
PROCESSMAKER_HOME=/path/to/processmaker XDEBUG_MODE=off php ./vendor/bin/phpunit --configuration phpunit.xml --no-coverage {test_path}
/usr/local/bin/phpunit vendor/processmaker/package-skeleton/{test_path}
```
3 changes: 3 additions & 0 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,9 @@
"@php rename-project.php"
]
},
"require": {
"swaggest/json-schema": "^0.12"
},
"require-dev": {
"squizlabs/php_codesniffer": "^3.9",
"friendsofphp/php-cs-fixer": "^3.50"
Expand Down
14 changes: 14 additions & 0 deletions projects/AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Projects assets

Versioned ProcessMaker artifacts for each domain live here.

Layout (see [ai-docs/structure.md](../ai-docs/structure.md) and root [AGENTS.md](../AGENTS.md)):

```
projects/{slug}/
├── bpmn/ # {slug}-{purpose}.xml
├── scripts/ # {slug}-{action}.php (basename = script title)
└── screens/ # {slug}-{purpose}.yaml (basename = screen title)
```

Publish order: upsert-script-php → upsert-screen-yaml → upsert-process-bpmn.
16 changes: 10 additions & 6 deletions projects/README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,12 @@
This folder contains the structure of each projects. Each of them are organized as follows:
- [project-name](./{project-name})/
- [project-name](./{project-name})/bpmn/ Here are placed the BPMN processes needed for this project
- [project-name](./{project-name})/screens/ Here are placed the yaml screens needed for this project
- [project-name](./{project-name})/scripts/ Here are placed the php scripts needed for this project
This folder contains the structure of each project. Each of them is organized as follows:

- `projects/{project-name}/bpmn/` — BPMN processes
- `projects/{project-name}/screens/` — YAML screens
- `projects/{project-name}/scripts/` — PHP scripts

See [AGENTS.md](./AGENTS.md) and root [AGENTS.md](../AGENTS.md).

## Notation rules
- Assets use kebab case notation for assets names. e.g. `project-name.bpmn`, `screen-name.yaml`, `script-name.php`

- Assets use kebab-case names, e.g. `project-name-intake.xml`, `project-name-form.yaml`, `project-name-save.php`
- Basename of script/screen files equals the ProcessMaker asset title
Loading