App package layout

What a pack must contain.

Source docs/en/site/sdk-appsdk-pack.md

What a pack must contain.

Readers: people who will hand-build a runnable workspace app from scratch. Runtime root: {RUNTIME_DIR}/workspaces/{workspaceId}/apps/{appSlug}/

1. Full directory

{appSlug}/
├── app.json                 # UI and data model (authors change this most)
├── manifest.json            # Manifest (platform writes: display name, assembly, intents…)
├── data/
│   └── app.db               # Business SQLite (platform creates tables from entities)
├── schema/
│   └── 001_init.sql         # DDL generated from entities
├── logic/
│   ├── handlers.py          # Custom-action entry (must be runnable when there are script actions)
│   └── *.py                 # Optional: business helpers (for example generate_profile.py)
├── scripts/                 # Optional: assemble/tool scripts (copied into the sandbox on invoke)
├── assets/                  # Optional: HTML templates, static assets
├── references/              # Optional: pipeline.json, field-mapping.json, and similar
└── skills/
    └── SKILL.md             # Notes so agents can call this app from conversation (often platform-generated)

2. Required vs optional

2.1 Minimal usable app (local register + list only)

For example a “notebook”: only form + list, built-in CRUD.

Item	Required?	Notes
`app.json`	Yes	≥1 entity, ≥1 view
`manifest.json`	Yes	Normally written by platform “create app”; do not hand-break `app_id`
`data/app.db`	Yes	Generated on first init/migrate
`schema/*.sql`	Yes	Aligned with entities; after entity changes the platform migrates extra columns
`logic/handlers.py`	Usually a stub on disk	No custom `actions` → no business to implement; with `impl=script` you must implement `handle`
`actions`	Not needed	Can omit for CRUD-only
`scripts/` `assets/` `references/`	Not needed

2.2 App with “one-click work” (actions + optional fetch)

For example “employee profile”: action_form + history list + script fetch producing HTML.

Item	Required?	Notes
Minimal set above	Yes
`app.json` → `actions` + `action_form`	Yes	Action id matches view `action`
Matching branch in `logic/handlers.py`	Yes	See App actions
Other `.py` under `logic`	As needed	Prefer splitting so one file does not grow huge
`references/pipeline.json`	Recommended	Declarative steps for multi-step fetch
`scripts/` + `assets/`	As needed	Needed when generating reports/HTML
`references/field-mapping.json`	As needed	Template slot fill
Workspace data connection and predefined queries	As needed	Every `query_id` in the pipeline must exist on the connection and the user must be allowed

3. Which directories enter the sandbox on invoke

When running a custom action, the platform copies these directories into a temporary working directory (does not mount the whole app directory as-is):

logic/ (must have handlers.py)
scripts/
assets/
references/

Not copied: data/, schema/, skills/, app.json, manifest.json. The business-DB path is injected via env / ctx["app_db"].

Therefore: templates, pipelines, and helper py that business scripts need must live in one of those four directories.

4.1 In-product “App pack” panel

After you open a lightweight app, top-bar “App pack” can browse text files in the directories above and edit-save allowlisted paths (same write scope as the app-development assistant). app.json / manifest.json are read-only preview. Details: App data pipeline §8.

5. File duties (quick lookup)

File	Who maintains	Duty
`app.json`	Author / app-development assistant	Entities, views, actions → decides what the UI looks like and which buttons exist
`logic/handlers.py`	Author	`handle(action, params, ctx)` dispatch; write DB, call platform bridge
`logic/*.py`	Author	Fetch orchestration, domain logic
`references/pipeline.json`	Author	Fetch step list (`query_id`, param templates)
`scripts/*.py`	Author	Pure transform (for example HTML assemble), prefer no side effects
`assets/*`	Author	Result layout templates
`data/app.db`	Runtime	App-private data such as history
`skills/SKILL.md`	Often auto-generated	How conversation calls this app’s actions

6. Mapping to “add a feature on the UI”

You want to add on the UI…	Change
Extra list column / form input	`app.json` entity fields + view `columns`/`fields` or action `params`
Extra “do work” button block	`actions[]` + `action_form` + new branch in `handlers.py`
Look up HR/business DB when doing work	In handlers call `ctx["platform"].query_run`; prefer a `pipeline.json`
Generate an openable report after work	Assemble HTML → `platform.save_upload` → return `upload_id`; list entity has `upload_id`
Only add/remove local records	`form`/`list` + built-in CRUD; you need not write script logic

Detailed steps: App actions · App data pipeline · Hand-build an app.