STaurtomation/docs/specs/001-staurtomation.md

---
status: draft
---

# STaurtomation — Design

- **Date:** 2026-10-29
- **Status:** Draft for owner review (builder-check questions answered 2026-10-30)
- **Owner:** Lucas Winther (copyright holder)
- **Background research:** `docs/research/` (licensing analysis of n8n, feature/pricing comparisons of n8n, Kestra, Windmill, Activepieces). Sanitized for clean-room use.

Marking convention: items the owner decided are stated plainly. Items marked **[call]** are the designer's call — sensible defaults the owner has not explicitly confirmed; the builder may revisit them with a stated reason.

---

## 1. Intent

n8n, Kestra, Windmill and Activepieces are all "open core": the free edition is usable, but the features that real organisations need — SSO, multi-user with roles, shared projects, git/environments, external secrets, log streaming, audit logs, HA — sit behind subscriptions or proprietary licenses. Several of them cannot legally be unlocked or forked into a product.

STaurtomation is a **workflow automation platform that is completely open**, with **every feature available to everyone**, no subscriptions, no license keys, no proprietary code. It aims to replace all four products over time, starting with n8n.

### Who it is for

1. **Homelabbers.** One self-hosted box for glue: centralising notifications, integrating with OpenClaw, smart-home automation, and small scheduled jobs that would otherwise each need their own Docker image or cron entry. Must be light and work as a single-user install with team features invisible until needed.
2. **Universities**, with somewhat non-technical staff building automations. Visual editor first, clear errors, and institutional sign-in (SAML/OIDC: Entra ID, Authentik, Shibboleth-style IdPs), many users, shared projects, roles.
3. **Companies**, primarily for small-scale prototyping. Ease of use and low-maintenance operation (STaurtomation keeps nodes and the platform itself updated, under admin-controlled rules) matter most. Scheduled AI queries are a core use case.

### What success looks like **[call]**

- A non-technical university staff member builds, tests (with test data and visible node input/output) and schedules a working workflow without help.
- The same install stays up to date for months under admin-set update rules without breaking existing workflows.
- An n8n user imports their workflows, sees clearly what converted and what didn't, and runs them.
- A homelabber goes from `docker compose up` to a running scheduled workflow in minutes.

---

## 2. Goals, non-goals, anti-goals

### Goals

- **Feature superset** of n8n, Kestra, Windmill and Activepieces, **including all of their premium/enterprise features**, delivered in phases (§9). Release 1 targets n8n.
- **Importers** for each product's workflow format.
- **Compatibility layers** to run third-party nodes: n8n community nodes first; later Kestra plugins and Activepieces pieces.
- **Polyglot code execution** via a runner architecture (TypeScript/Bun and Python first; R, Rust, Java, C# later).
- **AI on equal footing across providers**, plus an in-editor AI workflow assistant.
- **Admin-controlled updates** with semver rules and prominent security notices.

### Non-goals (for now)

- A hosted SaaS offering run by the project.
- Matching every one of n8n's ~400+ built-in integrations at launch (§6.4 defines the release-1 node set; the rest arrive via community-node compatibility and later node packages).
- Heavy data-engineering orchestration (Kestra/Airflow-style backfills at scale) in release 1 — later phase.

### Anti-goals (failure even if it "works")

- **Any proprietary or license-incompatible code in the codebase.** A single contaminated file undermines the whole project.
- **Any feature gated by edition, license key, user count or payment.**
- **Becoming developer-only** (Windmill/Kestra-style learning curve). Code is available; it is never required for common tasks.
- **Forced updates.** Nothing updates without an admin-configured rule allowing it.
- **Silent data loss on import.** Unsupported things are kept and flagged, never dropped.

---

## 3. Constraints

### 3.1 Licensing and ownership

- **License:** AGPL-3.0-or-later for the whole project. **[call: AGPL over plain GPL]** — owner chose "GPL/AGPL"; AGPL is chosen because STaurtomation is network software and AGPL closes the hosted-modification gap.
- **Ownership:** the owner retains copyright and the freedom to relicense or dual-license. Therefore **all outside contributions require a Contributor License Agreement (CLA)** granting the owner the necessary rights. **[call: CLA rather than DCO-only, since DCO does not preserve relicensing rights]**
- Every source file carries an SPDX header: `SPDX-License-Identifier: AGPL-3.0-or-later`.
- **Dependencies:** only licenses compatible with AGPL-3.0 (MIT, BSD, ISC, Apache-2.0, MPL-2.0, LGPL, GPL-3.0, AGPL-3.0, etc.). CI enforces this with an automated license allowlist check; unknown or incompatible licenses fail the build.
- **Trademarks:** never use "n8n", "Kestra", "Windmill" or "Activepieces" as or in product, package or node names. Nominative use only ("imports n8n workflows", "compatible with n8n community nodes"), with a non-affiliation note in docs.

### 3.2 Clean-room rules (non-negotiable)

These go into the repository's agent instructions (`CLAUDE.md`/`AGENTS.md`) and `CONTRIBUTING.md`.

1. **No code copied** from n8n, Kestra, Windmill, Activepieces or any other repository unless its license is permissive and AGPL-compatible **and** the copy is recorded in `THIRD_PARTY.md` with source, license and commit. In practice: do not copy from those four at all, including their permissively licensed parts, unless the owner explicitly approves.
2. **Do not read the source code** of n8n, Kestra, Windmill or Activepieces (including their `.ee`/enterprise code, internal packages, and the `n8n-workflow` / `n8n-nodes-base` packages) while working on STaurtomation. This applies to humans and AI agents, including via web search results and npm package contents.
3. **Allowed inputs:** public documentation and user guides, published file formats observed from exported files, public REST API docs, published specifications (e.g. Windmill's OpenFlow spec, which is Apache-2.0), observed behaviour of a running instance, screenshots, and third-party MIT/Apache-licensed community nodes/plugins (as *test subjects* for compatibility — reading them to learn which interface they consume is allowed; copying their code into STaurtomation is not, except under rule 1).
4. **Interface reimplementation** (for compatibility layers, §7) is done from documentation and from observing what community packages call, never from the original library source. Each compatibility layer keeps a `PROVENANCE.md` noting the documentation pages and test packages used.
5. If anyone realises they have been exposed to prohibited source for a given area, they record it and do not implement that area.
5a. **AI agents** (the expected primary builders) are allowed to implement every area, including the high-risk ones, despite the likelihood that their training data contains public source of those products. Because the project must supersede these tools, never copy them, the following **guards are mandatory**:
   - **Similarity scanning in CI:** an automated code-similarity check (token/winnowing fingerprinting, e.g. JPlag or an equivalent tool, used as a CI tool only, not a dependency) compares every change against fingerprints of n8n, Kestra, Windmill and Activepieces. The reference corpus is fetched and fingerprinted inside an isolated CI job; reports show only *our* file, line range and score — never the matched third-party code — so builders are not exposed. Above-threshold matches block merge until a human reviews and rewrites.
   - **Per-PR provenance note** (PR template): which public docs, specs, exported files or observed behaviour the change was based on; affirmation that no prohibited source was consulted. Mandatory for compatibility, importer and expression work.
   - **Dependency denylist:** CI fails if the lockfile contains `n8n-workflow`, `n8n-core`, `n8n-nodes-base`, `@n8n/*`, `@n8n_io/*`, `@activepieces/*` (except as listed test fixtures outside the shipped product, if ever approved), or Kestra/Windmill packages.
   - **Agent tooling rules:** agents must not clone, fetch, `npm view`/unpack or web-browse into those products' source repositories or packages; only their documentation sites and exported artifacts.
   - **Human sign-off** on PRs touching the importer, expression compatibility, or any compatibility layer.
   - **No naming mimicry:** internal names, file layout and identifiers follow STaurtomation's own conventions, not the original products'. Where n8n-facing names are unavoidable (importer mapping tables keyed by n8n node type strings, compat-layer public interface), they are confined to the importer/compat packages.
6. **Legal review gate:** the n8n community-node compatibility layer (§7.1) reimplements a third party's programming interface. That is generally defensible (interfaces/functionality are not protected expression in the EU — *SAS v WPL*; *Google v Oracle* by analogy in the US) but is the project's highest legal-risk area. It ships only after the owner obtains legal review. Not legal advice.

### 3.3 Platform conventions (from `bun init`'s CLAUDE.md, adopted verbatim in the repo)

- Bun, not Node.js: `bun <file>`, `bun test`, `bun build`, `bun install`, `bun run`, `bunx`. Bun loads `.env` automatically (no dotenv).
- `Bun.serve()` with routes and WebSockets — no Express.
- `bun:sqlite` for SQLite, `Bun.sql` for Postgres, `Bun.redis` for Redis, built-in `WebSocket`, `Bun.file`, `` Bun.$ ``.
- Frontend via HTML imports served by `Bun.serve()` — no Vite.

---

## 4. Architecture (decided parts)

### 4.1 Stack

| Area | Choice |
|---|---|
| Language/runtime | TypeScript on Bun |
| HTTP/API/WebSockets | `Bun.serve()` routes, with a thin in-house layer for auth, input validation and permission checks **[call: no web framework]** |
| Frontend | React + TypeScript SPA via Bun HTML imports; React Flow (xyflow) for the canvas; shadcn/ui + Tailwind (via `bun-plugin-tailwind`); TanStack Query and TanStack Router |
| Databases | SQLite (`bun:sqlite`) for single-box installs; PostgreSQL (`Bun.sql`) for multi-user/HA. Same schema, both supported and tested in CI. |
| Queue/coordination | Redis (`Bun.redis`) optional, needed for HA/multi-main **[call: Postgres-only queue is acceptable if the builder prefers; must work with zero extra services in single-box mode]** |
| Tests | `bun test` |
| Packaging | One Docker image containing server + editor + a default Bun runner; Docker Compose and Helm examples |

### 4.2 Deployment shapes

- **Single box (homelab):** one container, SQLite, embedded runner. Team features exist but stay out of the way (single owner account, no project UI clutter until a second user or project is created) **[call]**.
- **Team (university/company):** Postgres, one or more main instances, separate runners.
- **HA:** multiple main instances behind a load balancer (leader election for scheduler/trigger ownership), many runners. All of this is free — it is one of n8n's paid features.

### 4.3 Runners

Modelled on GitHub/Gitea Actions runners and on the concept (not the code) of n8n's task runners.

- A runner is a separate process, possibly on another machine. It **registers** with the server using a registration token, connects outward over **WebSocket**, receives jobs, executes them, streams logs and results back.
- **Runner types per language:** Bun/TypeScript and Python in release 1; R, Rust, Java, C# later. A Node.js runner exists as fallback for community nodes that don't work on Bun **[call]**.
- **Labels** route jobs (`python`, `gpu`, `lan`, …). Scaling = add runners.
- **Isolation modes:** execute in-process (fast, trusted code) or in a throwaway container (untrusted community nodes, user code, the "job that would need its own Docker image" homelab case). Admin chooses defaults per project **[call]**.
- **Runner protocol is documented and versioned** (`docs/runner-protocol.md`) so third parties can write runners for new languages without core changes.
- Runners never receive more secrets than the job needs.

### 4.3a Threat model **[call]**

- On multi-user installs, workflow editors are **not** trusted with the server or with other projects' data. Instance admins are trusted.
- Expressions always run in a sandbox with no file/network/process access, on every install type.
- **Team installs default to container isolation** for user code steps and community nodes; in-process execution is an explicit per-project admin opt-in. Single-box installs default to in-process (one trusted owner) and offer container mode when a container runtime is available (Docker socket or rootless Podman mounted into the container — documented as optional in Compose).
- Credentials are decrypted only for the job that uses them and are never returned to the editor UI after saving.

### 4.4 Workflow engine

- A workflow is a directed graph of nodes. Data flows between nodes as **lists of items** (each item a JSON object plus optional binary attachments). **[call]** This model is chosen because it makes n8n import and community-node compatibility feasible; it is a well-known general concept.
- Executions are persisted with per-node input/output (subject to retention and redaction settings).
- Triggers: manual, schedule, webhook, called-by-another-workflow, form, chat, plus trigger nodes from packages.
- **Expressions:** an expression language for referencing previous nodes' data inside parameters, evaluated in a sandbox. A separate **n8n-expression compatibility mode** (built from n8n's public docs) is used for imported workflows so they keep working **[call]**.
- Binary data stored on filesystem or S3-compatible storage (free; paid in n8n).
- Concurrency limits per workflow/project/instance; retries with backoff; error workflows.

### 4.5 Data model highlights **[builder decides details]**

Users, identities (linked IdP accounts), roles, projects, project memberships, folders, workflows (+ versions), credentials (encrypted at rest), variables, executions (+ per-node data), tags, environments, audit events, update/package state.

---

## 5. Identity, access and governance

### 5.1 Authentication

- **Library:** Better Auth (MIT) for username/password, sessions, TOTP 2FA, OAuth social login and OIDC/SAML via its SSO plugin; `@node-saml/node-saml` (MIT) as fallback for SAML edge cases; `ldapts` (MIT) for LDAP/AD. **[call]** The owner suggested Passport; the call is Better Auth because it is framework-agnostic (fits `Bun.serve()`'s standard `Request`/`Response`) and covers sessions/2FA/orgs. **First builder task: verify Better Auth's SAML and SCIM maturity and Bun compatibility. If it falls short, use Passport (MIT) with the relevant strategies behind an adapter.**
- **Must-have:** SAML 2.0 and OAuth2/OIDC. **Entra ID and Authentik are first-class:** step-by-step setup docs and automated integration tests (Authentik in a test container; Entra ID against a test tenant, possibly a manual/nightly job).
- Also: LDAP/AD, SCIM 2.0 provisioning, local accounts, 2FA with admin enforcement, social login (Google/GitHub/Microsoft). **[call on scope; owner delegated]**
- API keys with scopes for the public API.

### 5.2 Identity mapping

- Map IdP groups/claims/attributes → instance roles, project memberships and project roles, with a rules UI (e.g. "Entra group `automation-admins` → instance admin").
- **Admins can make custom edits per user.** Manual edits are flagged as overrides and survive subsequent logins/syncs; an explicit "reset to IdP mapping" action reverts them **[call on override semantics]**.

### 5.3 Authorization

- Instance roles: owner, admin, member **[call]**.
- Projects: unlimited, with project roles admin / editor / viewer, plus **custom roles** built from fine-grained permissions.
- Sharing workflows and credentials across projects/users; personal projects per user.
- Folders within projects.
- Permission checks are enforced server-side on every API route and in the public API; the UI only reflects them.

### 5.4 Governance features (all free)

- **Audit log** of security-relevant and admin events, searchable, exportable, retention-configurable.
- **Log streaming** of audit and execution events to destinations: syslog, webhook, Sentry, OpenTelemetry/OTLP, plus file/stdout **[call on destination list]**.
- **Execution data retention**: global and per-project max age / max count, pruning, and what to save (success/failure/manual/progress).
- **Data redaction**: per workflow/project option to not store input/output of executions, or to mask fields.
- **Metrics**: Prometheus endpoint + OTLP metrics; health endpoints.
- **Insights**: dashboards of executions, failures, durations, time saved, over any date range.
- **Worker/runner view**: live status of runners, jobs, load.
- **2FA enforcement**, session policies.

---

## 6. Building and running workflows

### 6.1 Editor

- Canvas (React Flow) with node panel, parameter forms, expression editor with autocomplete, keyboard shortcuts, copy/paste of nodes as JSON.
- **Test data and inspection (must-have):**
  - Run a single node, a node and everything upstream, or the whole workflow from the editor.
  - **See each node's input and output** after a run, as table / JSON / schema views, including binary previews.
  - **Pin test data** on any node (paste JSON, edit, or pin from a previous execution's output) so downstream nodes can be built without re-triggering upstream ones. Pinned data is used only for manual/test runs, never production runs.
  - **Debug from a past execution:** load a past (e.g. failed) execution's data into the editor and re-run.
- **Workflow history:** every save versioned, unlimited by default (retention configurable), named versions, visual diff between versions, restore.
- Execution list with search/filter including custom execution data.
- Templates/examples gallery **[call: local, shipped with the app; no external template service required]**.

### 6.2 Sub-workflows (must-have)

- A workflow can call another workflow (sync, waiting for the result; or async, fire-and-forget), passing input items and receiving output items.
- Callable workflows declare an input schema (fields and types) so callers get a form, and an output.
- Permission controls on who may call a workflow (same project, specific projects, any).
- Recursion/loop protection and depth limits.

### 6.3 Credentials, variables, secrets

- Credentials encrypted at rest with an instance key; credential types defined by node packages; OAuth2 credential flow handled by the platform.
- **Variables** (instance/project/environment scoped) referenced in expressions.
- **External secrets** providers: HashiCorp Vault/OpenBao, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, Infisical, Bitwarden Secrets Manager, plus environment/file-based injection **[call on list]**.

### 6.4 Release-1 built-in nodes

- **Triggers:** manual, schedule (cron + simple "every X" picker), webhook, called-by-another-workflow, form, chat.
- **Core/flow:** HTTP request, if, switch, merge, loop/split-in-batches, set/edit fields, code transform helpers (filter, sort, limit, aggregate, split out, remove duplicates), wait, execute sub-workflow, stop-and-error, error trigger, respond-to-webhook, no-op. **[call on exact list]**
- **Code:** TypeScript/JavaScript (Bun runner) and Python (Python runner).
- **AI:** chat/completion node, agent node with tools (other nodes and sub-workflows usable as tools), embeddings, structured output, agent memory (buffer + database-backed), document loaders/text splitters, vector store nodes (pgvector, Qdrant, in-memory) with a retriever, and simple evaluations (run a workflow over a test dataset and score outputs) **[call: the AI items beyond chat/agent are phase 3]**. See §8.
- **Human-in-the-loop:** pauses the execution until a person approves / rejects / fills a form. Delivery via email, link, in-app notification and (through other nodes) chat; assignable to a user or role; optional deadline with a timeout branch; resumes durably across restarts.
- **Data:** built-in data tables (simple tables stored in STaurtomation, usable from workflows) **[call]**.
- Everything else comes via node packages and the compatibility layer.

### 6.5 Node packages and SDK

- Nodes are distributed as packages (npm-compatible) with a STaurtomation node SDK (TypeScript), versioned with semver.
- Node versions installed side by side; each workflow pins the node versions it was built with until explicitly upgraded.
- Admin controls: allowlist/denylist of packages, private registry support.

### 6.6 Environments and source control (git)

- Connect an instance (or project) to a git repository (Gitea, GitHub, GitLab, any git over SSH/HTTPS).
- Workflows, credentials **(metadata only, never secrets)**, variables, folders, tags, data-table schemas serialized to a stable, diff-friendly text format.
- Push/pull from the UI and API; branch-per-environment model (e.g. `dev` → `staging` → `prod`), with an instance bound to a branch and optional read-only protection on production instances.
- Diff and conflict display before pulling/pushing; promotion between environments via git merge or an in-app "promote" action.

### 6.7 Public API, CLI, MCP

- Versioned REST API covering everything the UI can do (OpenAPI spec published).
- CLI for import/export, user management, backups.
- MCP server exposing selected workflows as tools for external AI agents **[call]**.

---

## 7. Importers and compatibility layers

### 7.1 n8n (release 1)

- **Fidelity (owner decision): best effort, with clear warnings.** STaurtomation's engine follows its own semantics; it does not have to reproduce n8n's execution order, item linking, merge/branch waiting or error behaviour exactly. The importer warns per workflow and per node where behaviour may differ (known-difference list maintained in docs), and imported workflows start inactive so the user tests them first. No reference n8n instance is required in CI.
- **Importer:** accepts n8n workflow JSON (file, paste, or bulk directory/ZIP). Behaviour learned from exported files and public docs only.
  - Nodes with a STaurtomation equivalent are converted; their parameters mapped; n8n expressions kept and evaluated in n8n-expression compatibility mode.
  - Nodes that are n8n community nodes are mapped to the installed community package via the compatibility layer.
  - Anything else becomes a **placeholder node** that preserves the original type and parameters, is visibly marked, and blocks activation until resolved.
  - A per-import **report**: converted / via compatibility / placeholders, plus credential types needing setup (credentials are not exported by n8n with secrets; user re-enters them).
  - Optional import of n8n credentials export files and the n8n public API (pull directly from a running n8n instance) **[call]**.
- **Community-node compatibility layer:** loads n8n community node npm packages (third-party, usually MIT) and runs them in a Bun runner (Node.js runner fallback), providing a clean-room reimplementation of the node-facing interface those packages consume — built from n8n's public node-development docs and from observing what MIT-licensed community packages call. The substitute module that packages import must be our own code. See §3.2 rules 3–6, including the legal-review gate.
- **Built-in n8n node coverage:** n8n's built-in nodes are under n8n's restrictive license and cannot be reused. STaurtomation writes its own equivalents from public docs; the importer maps n8n node type names to them. Coverage grows over time, prioritised by how commonly nodes appear in imported workflows **[call]**.

### 7.2 Later phases

| Product | Importer | Compatibility |
|---|---|---|
| Kestra | YAML flows → STaurtomation workflows (tasks → nodes, triggers, inputs, namespaces → projects/folders) | Java runner able to execute Kestra plugins (Apache-2.0) through a clean-room reimplementation of the plugin interface from Kestra's public docs |
| Windmill | OpenFlow JSON/YAML (published Apache-2.0 spec) and scripts → workflows and code nodes | Scripts run natively on the matching language runner |
| Activepieces | Exported flow JSON → workflows | Activepieces pieces (MIT, TypeScript) via a pieces adapter **[call: desirable, not committed]** |

### 7.3 Feature superset from the other three (later phases)

- **From Kestra:** flows-as-code (YAML representation of every workflow, editable side-by-side with the canvas), namespaces, event triggers (Kafka, AMQP, MQTT, etc.), backfills, scheduled purge, worker groups.
- **From Windmill:** scripts as first-class reusable units in many languages, per-script dependency locking, app/UI builder for internal tools, workspaces, Postgres CDC/WebSocket/SQS/NATS triggers, multiplayer editing.
- **From Activepieces:** simple step-based builder mode for beginners, approvals, tables, embedding/white-label SDK for SaaS builders, MCP-first agents.
- And each product's premium features listed in `docs/research/`.

---

## 8. AI

- **Providers on equal footing:** OpenAI, Anthropic, Google, Mistral, OpenRouter, Ollama, any OpenAI-compatible endpoint (LM Studio, vLLM, …), and OpenClaw. One provider interface; each provider a small plugin; keys stored as ordinary credentials (so external secrets work).
- **Workflow assistant** (Supabase-assistant-like) in the editor: describe what you want → it builds/edits the workflow, explains nodes, diagnoses failed executions.
  - Configured with a **system-wide** API key (admin) and/or a **personal** key on a user's account. **[call]** Personal key takes precedence; admins can disable the system key for some roles; usage visible per user.
  - Every change is proposed as a **diff on the canvas** that the user accepts or rejects; it never activates or runs a workflow without confirmation **[call]**.
  - Works with any configured provider, including fully local models.

---

## 9. Updates and maintenance

- **Never forced.** Updates apply only under admin-configured rules.
- **Semver update rules**, separately for the core and per node package: off (notify only) / patch only / minor+patch / pinned. Defaults: core = notify only; node packages = patch only **[call]**. Optional "auto-apply security fixes only".
- **Clear notices:** banner + updates page with changelogs; **security fixes are highlighted** with severity and advisory/CVE ID; notifications via email, webhook, and an internal "update available" trigger usable in workflows.
- **Safety:** pre-migration database backup; node versions side-by-side so running workflows aren't changed underneath; one-click rollback of node packages; documented core downgrade path **[call]**.
- **Supported install methods in release 1 [call]:** Docker/Compose and Helm only. Core updates are therefore notices plus automatic database migrations on start; no in-app core self-updater in release 1. Node-package updates are applied live by the server and coordinated across HA main instances (one instance installs, all switch over together) and runners (fetch on demand).
- **Container installs:** the app does not replace its own image; it shows the new tag and the exact command, and is compatible with tools like Watchtower.
- **Advisories:** the project publishes a signed release/advisory feed the app polls (can be disabled for air-gapped installs) **[call]**.

---

## 10. Phasing

| Phase | Content |
|---|---|
| 0. Foundation | Repo, LICENSE (AGPL-3.0-or-later), CLA, `CLAUDE.md`/`AGENTS.md` with clean-room and Bun rules, `CONTRIBUTING.md`, `THIRD_PARTY.md`, CI (tests, typecheck, lint, dependency-license allowlist, SPDX header check) |
| 1. Core | Engine, item model, expressions, runners protocol + Bun & Python runners, SQLite/Postgres, editor with test data/IO inspection/pinning, sub-workflows, release-1 nodes, credentials, local auth |
| 2. Teams | SSO (SAML/OIDC with Entra ID & Authentik tests, LDAP, SCIM), identity mapping, RBAC + custom roles, projects, sharing, folders, variables, audit log |
| 3. n8n parity | Git environments, external secrets, log streaming, retention/redaction, workflow history + diff, insights, metrics, runner view, HA multi-main, S3 binary storage, public API + scopes, update system, AI nodes + assistant, human-in-the-loop |
| 4. n8n migration | n8n importer, n8n-expression compatibility, growing built-in node coverage |
| 4b. Community-node compatibility | n8n community-node layer — **only after legal review** |
| 5+ | Kestra importer/compat + Java runner; Windmill importer + R/Rust/C# runners; Activepieces importer/pieces; feature superset items in §7.3 |

### Releases

- **Release 1 — homelab-ready (owner decision: homelab first, no compatibility layer).** Phase 0 + Phase 1, plus from later phases **[call on this selection]**: AI chat/agent nodes, human-in-the-loop, update notices (security highlighting; node-package semver rules), retention settings, Prometheus metrics, and the **best-effort n8n importer** (§7.1, built-in node mapping + placeholders, no community nodes). Single-box Docker Compose install is the reference deployment. Local accounts plus OIDC login are enough. **[call: OIDC in R1 because homelabbers commonly run Authentik]**
- **Release 2 — teams/n8n parity:** rest of Phases 2–4 (SAML incl. Entra ID, LDAP, SCIM, RBAC, projects, git environments, external secrets, log streaming, audit, HA, AI assistant, etc.).
- **Release 3 — community-node compatibility** (Phase 4b), gated on legal review; ships when cleared, independent of other work.
- Release 1 must still be production-quality in what it includes (stable schema migrations from day one, upgrade path to later releases, security hardening).

The builder may reorder within phases if dependencies demand it.

---

## 10a. Who builds it (owner decision)

Primarily a **team of AI agents**, with human contributors (under the CLA) and possibly a part-time maintainer provided by the owner's university. **Optimise for AI-first development:** small, independently verifiable tasks; strong automated checks (types, tests, license/similarity guards) so agents get fast feedback; thorough agent docs (`CLAUDE.md`/`AGENTS.md`, per-package READMEs, ADRs for decisions); no tribal knowledge. No fixed deadline.

Owner-supplied resources, needed by Release 2: an Entra ID test tenant + CI credentials; legal review of the compatibility approach (blocks Release 3 only).

## 11. Left to the builder

- Detailed database schema, migration tooling, internal module layout (monorepo layout recommended).
- Queue implementation (Postgres-based vs Redis), scheduler/leader-election design.
- Expression language syntax for native STaurtomation workflows and the sandboxing approach.
- Workflow serialization format for git (must be stable and diff-friendly).
- Exact runner protocol messages, container isolation backend (Docker/Podman/rootless).
- UI design system details, beyond the stack in §4.1.
- Testing strategy beyond: `bun test` unit/integration tests, both databases in CI, IdP integration tests for Entra ID and Authentik, importer golden-file tests built from self-made n8n exports.
- Which further integrations to build first after the release-1 node set.

## 12. Open verification items for the builder

1. Better Auth: SAML maturity, SCIM plugin maturity, Bun compatibility (fallback: Passport behind an adapter).
2. Bun compatibility of the most popular n8n community nodes (decides how much the Node.js fallback runner matters).
3. React Flow and the remaining frontend stack under Bun's bundler (HTML imports) with Tailwind via `bun-plugin-tailwind`.
4. Legal review of the compatibility-layer approach (§3.2 rule 6) before §7.1's compatibility layer ships.