Modular Project Architecture & Unattended Lifecycle
This guide documents Kinenix's Self-Contained Project Bundle architecture, subflow execution standards, and the complete lifecycle from development to unattended deployment.
Your bundles live in your flows folder (default ~/kinenix-flows), outside the Kinenix repository; kinenix init creates them there. The layout below is the inside of one bundle, wherever it lives. See Where your flows live.
1. Self-Contained Project Bundle Overview
Enterprise automation workflows often contain multiple sub-processes, data files, and external templates. To avoid path dependencies, broken references, or variable collisions, Kinenix organizes workflows into Self-Contained Project Bundles:
flows/
├── @shared/ # Cross-project reusable library
│ ├── web_login_sso.json # SSO login component
│ └── send_email.md # Reusable Gmail/SMTP component
│
└── accounting/ # Department / Business Domain
└── invoice_tax_filing/ # 1 Self-Contained Project Bundle
├── flow.md # Main flow, the file you edit (source of truth)
├── config.json # Project-specific configuration (Auto-loaded)
├── .env # Optional local secrets (Git-ignored)
├── subflows/ # Project-specific subflows
│ ├── download_tax_pdf.json
│ └── extract_table.json
└── assets/ # Local templates, configs, test data
└── tax_template.xlsx
Key Principles:
- Portability: All references to assets and subflows inside a project bundle use Relative Paths (e.g.
./assets/tax_template.xlsx,./subflows/extract_table.md). - No Hardcoded Absolute Paths: Workflows never depend on developer-specific paths (e.g.,
C:\Users\Dev\...), ensuring seamless portability across different machines, VMs, or operating systems. - Atomic Units: A single project directory represents one coherent unit of business automation that can be developed, tested, versioned, and deployed as a standalone bundle.
- Decoupled Settings (
config.json): Engine automatically auto-loadsconfig.jsonfrom the flow bundle directory into${config.*}and top-level variables. Business users or admins can modify endpoints, email recipients, or thresholds without alteringflow.json. - Local Secrets (
.env): Optional project-level.envis automatically parsed and mapped to${env.*}for local execution without leaking credentials to version control. OneNAME=valueper line;export NAME=valueworks too, a line starting with#is a comment, and so is# noteafter a value. Put a value that holds#in quotes (NOTE='room # 5'); a#without a space before it stays in the value (PASSWORD=abc#123). A variable already set in the environment wins over the file.
2. Calling Subflows (flow.call)
The flow.call action runs another flow (a subflow) and can use the value it returns. Write subflows in the same Markdown format as flow.md; flow.call compiles a .md subflow when it runs, so no .json file is kept next to it. Existing .json subflows still work, and a target without an extension (./subflows/extract_table) uses the .md file when both exist.
2.1 Subflow of the Bundle (./subflows/)
### 3. Extract Table Data (`flow.call`)
- **flow:** ./subflows/extract_table.md
- **inputs:** {"pdf_path": "${downloaded_pdf}"}
- **output_var:** `extracted_data`
A subflow inside the bundle works like part of the main flow:
- Config: it sees the bundle's
${config.*}. Aninputskey namedconfigis merged over it, key by key. - Folder: relative paths (
./output/...,./assets/...) resolve against the bundle folder, notsubflows/. A subflow can still call another subflow by a path relative to its own file (./other.mdfromsubflows/). - Data: other values reach the subflow only through
inputs. The subflow declares them in its## Variables, with defaults;kinenix validatereports aninputskey the subflow does not declare.
The hello example (kinenix init demo --example hello) calls subflows/make_greeting.md once per name.
2.2 Shared Component (@shared/)
### 1. Send LINE Alert (`flow.call`)
- **flow:** @shared/notify_line.md
- **inputs:** {"message": "Invoice tax filing completed successfully.", "token_env": "LINE_TOKEN"}
Components in @shared/ (or any flow file outside the calling bundle) are used by many projects, so they keep their own folder and their own config/config.json. Give them values with inputs: the component's ## Variables is its contract, and kinenix validate checks the names.
When a shared component needs many values from the caller's config, inherit_config: true passes the caller's whole config. The caller's keys win; keys only the component defines keep the component's defaults:
> Requires: kinenix>=0.2.0b4
### 2. Monthly Report (`flow.call`)
- **flow:** @shared/monthly_report.md
- **inherit_config:** true
inherit_config needs Kinenix 0.2.0b4 or later; the > Requires: line under the flow's title makes older workers refuse the flow instead of running the subflow without the config.
This ties the component to the caller's key names, so prefer inputs for components used by projects with different configs.
2.3 Variable Scope Isolation
- When
flow.callexecutes a subflow, the child flow receives its own isolatedExecutionContext. - Only
inputs, the config described above, and runtime sessions (for example the active Playwright browser) are shared with the child flow. - Variables set inside the subflow do not overwrite the caller's variables. Values come back through
flow.returnandoutput_var, oroutputs.
2.4 Validation
kinenix validate, kinenix run, and the worker check every subflow whose path is fixed (not built from ${...}): that the file exists, its own problems (unknown actions and parameters, ignored lines), and the inputs names. Each subflow is checked once, also when subflows call each other.
3. Flow Lifecycle & Unattended Deployment Strategy
The project bundle structure directly enables a robust deployment pipeline to unattended robot workers (kinenix-worker):
Status: Stage 1 and the sandbox workspace in Stage 4 (
kinenix-worker run --sandbox) are implemented. Packaging, Hub distribution, the worker cache, and WebSocket streaming (Stages 2, 3, 5) are planned. See roadmap.md. The proposal that replaces Stages 2 and 3 (signed packages that workers pull from the Hub, no WebSocket) is design/flow-deploy.md.
[ Developer Machine ] -> [ Kinenix Hub ] -> [ Unattended Worker Daemon ]
Local Dev & Test Package & Version Isolated Sandbox Execution
Stage 1: Local Development & Verification
- Developer authors and tests the workflow locally within
flows/<dept>/<project>/. - Run and debug via CLI:
kinenix run <project_name>. - All assets remain inside
./assets/and logs are written to centrallogs/.
Stage 2: Packaging & Versioning
- The project bundle directory is packaged into a versioned archive (e.g.
invoice_tax_filing-1.0.0.kinxor.zip). - Any referenced
@shared/flows are inlined by the packaging tool into the bundle, ensuring the archive is 100% self-contained. - The package is published to Kinenix Hub.
Stage 3: Distribution & Local Worker Cache
- Background daemons (
kinenix-worker) running on target worker machines (Windows VMs, PCs, or Raspberry Pi) connect to Hub via WebSocket. - When a job is dispatched, the worker checks its local package cache (
~/.kinenix/packages/orC:\ProgramData\Kinenix\packages\). - If the requested version is not present or updated, the worker downloads and verifies the package archive.
Stage 4: Sandbox Workspace Isolation
- Prior to execution, the worker unpacks the project bundle into an isolated, per-job workspace directory:
- This ensures complete filesystem isolation, eliminates cross-job file locking or corruption, and allows clean workspace disposal after job completion.
Stage 5: Execution & Telemetry
- Worker executes the bundle:
kinenix-worker run <bundle>. - Step results, business metrics, and failure screenshots are streamed in real time to the Hub dashboard.
4. Testing Against Saved Pages
A web flow depends on pages it does not control: a changed button, a new cookie banner, or a renamed field breaks it in production. Testing it against saved copies of those pages catches the flow's own mistakes before it touches the real site, without internet, on any machine, and in CI.
- Save the pages the flow visits under
tests/pages/in the bundle (in the browser: Save page as, "Webpage, Complete"), and remove customer data from them. Open each saved page in a browser first: a page built by JavaScript may need its scripts to show the form, and then a hand-written HTML page with the same selectors is the better test page (batch_flows.md, rule 5). - Point the flow at them with a second settings file.
config/test.jsonholds only the keys that change for a test run; the rest comes fromconfig/config.json:{ "website_url": "tests/pages/quote_form.html", "input_csv": "input/test_requests.csv", "email": {"to": "me@example.com", "dry_run": true} }web.openandweb.gotoopen a path that names a file in the bundle (heretests/pages/quote_form.html) as a local page, so the same file works on every machine. - Run with it: Each key of the file replaces the same key of
config/config.jsonfor this run only; a key holding an object, such asemail, is replaced as a whole.--vars '{"config": {...}}'is applied on top, for a one-off change. - Check the outcome:
kinenix runexits with 1 for a technical failure, 3 when a business rule stopped it, and 8 when it finished with failed items (cli_guide.md, Exit Codes); compare the files underoutput/(rows written, failed items in the summary) with what the saved pages should give. Keep the saved pages and the test file in git with the flow, and refresh the pages when the real site changes.
A command that runs such a test and compares the results by itself (kinenix test) is planned for 1.6.0.