# Project Layout

Maestro BPMN Process Orchestration projects use BPMN XML as source and generated JSON files as package/runtime metadata.

## Canonical source files

- `<project>.bpmn` - BPMN process source and UiPath extension XML. For a new
  project, keep the BPMN source basename exactly aligned with the project
  directory/name. For example, `InvoiceTriageBpmn/InvoiceTriageBpmn.bpmn`, not
  `InvoiceTriageBpmn/invoice-triage-bpmn.bpmn`.
- `project.uiproj` - UiPath project metadata. Keep it in the same project
  directory as the main BPMN file: `InvoiceTriageBpmn/project.uiproj`, not next
  to the project directory.

For a new local project, place source files under a single project directory.
`uip maestro bpmn init <ProjectName>` takes a name, not a path, and writes under
the current directory; to land the project at a requested path, run it from that
path's parent with the leaf as the name, and either pass
`--skip-solution-registration` or make that parent a solution first — otherwise
the default behavior below inserts the `<ProjectName>Solution/` level.
`uip maestro bpmn init <ProjectName> --output json` nests that directory inside
a solution. Inside a solution it registers the project with the parent `.uipx`;
outside any solution it auto-scaffolds `<ProjectName>Solution/` and nests the
project inside (the response adds `Data.AutoCreatedSolution` =
`{ Name, Path, SolutionFile }` and reports `SolutionRegistration.Status:
Registered`; re-running is idempotent and reports `AlreadyRegistered`):

```text
ProjectNameSolution/             ← auto-scaffolded when init runs outside a solution
  ProjectNameSolution.uipx
  ProjectName/
    ProjectName.bpmn
    project.uiproj
    bindings_v2.json             ← generated; preserve as written
    entry-points.json            ← generated
    operate.json                 ← generated
    package-descriptor.json      ← generated
```

`init` writes all six files. Preserve the four generated ones as written —
that shape is the contract `pack` consumes.

With `--skip-solution-registration` the project lands bare instead, with no
solution wrapper (use it for a local-only project you do not intend to package
or operate):

```text
ProjectName/
  ProjectName.bpmn
  project.uiproj
  bindings_v2.json
  entry-points.json
  operate.json
  package-descriptor.json
```

If a **non-empty** directory already exists at the path you typed, init warns
and leaves it untouched — the project still lands in
`<ProjectName>Solution/<ProjectName>/`, not the existing directory.

## Generated or CLI-managed package files

- `bindings_v2.json` - resource bindings generated or enriched from BPMN and registry/connection metadata.
- `entry-points.json` - runnable start-event entry points and input/output schemas.
- `operate.json` - runtime/package metadata.
- `package-descriptor.json` - package manifest mapping generated files and BPMN content.

Treat these JSON files as derived unless a CLI contract explicitly identifies a field as user-authored. For source fixes, edit BPMN or rerun CLI enrichment rather than patching generated output by hand.

After source validation, generate the complete set with:

```bash
uip maestro bpmn refresh <project-path> --output json
```

Refresh regenerates all four files as one atomic set and local packaging
consumes that set — see
[local-metadata-regeneration-guide.md](local-metadata-regeneration-guide.md).
In particular,
`uip maestro bpmn pack <project-path> <OutputDir> --output json` does not create
a missing descriptor from only the BPMN and `project.uiproj`.

For the regeneration and drift-check contract, see [local-metadata-regeneration-guide.md](local-metadata-regeneration-guide.md).

## Package content

A synthetic local project authored without a CLI generator must still match the
metadata contract before packing: the root process follows the initializer's
shape (`isExecutable` omitted, or the equivalent `"false"` — never forced to
`"true"`), each root manual start event carries
`<uipath:entryPointId value="<uuid>" />`, `operate.json` has `"main"` plus
`"contentType": "ProcessOrchestration"`, and `package-descriptor.json` maps the
BPMN file and generated JSON. `uip maestro bpmn refresh <project-path>`
produces that shape; for the exact JSON, see
[local-metadata-regeneration-guide.md](local-metadata-regeneration-guide.md#source-only-fallback).
Prefer the files produced by `uip maestro bpmn init`, and do not translate a
descriptor shape from another UiPath project type.

A Process Orchestration package content folder contains:

- One or more `.bpmn` files.
- `bindings_v2.json`.
- `entry-points.json`.
- `operate.json`.
- `package-descriptor.json`.

The package descriptor maps the BPMN file and generated JSON by name. The entry point file path references the BPMN file and start event as `/content/<bpmn-file>#<start-event-id>`, using the root start event's unique entry point ID.

## Authoring boundary

Authoring owns local files and local validation. It can create or edit BPMN source, preserve existing generated files for comparison, and run validation/generation commands. It stops before upload, debug, publish, or run unless the user explicitly consents.

Operate owns cloud-side side effects: upload, publish, deploy, debug, process run, instance lifecycle, and cloud resource refresh.

Diagnose owns post-run inspection: incidents, variables, element executions, deployed assets, traces, and correlation back to BPMN element IDs.