Project layout

The repository is a platform plus its own example corpus. Some directories hold the code you edit, some hold the evidence a run produces, while some are install output that Git ignores. This page walks the top level so you know where a change belongs before you make it.

#Source and library directories

automations/ holds the automations themselves, one *.automation.ts file each. Every file default-exports a defineAutomation definition: its id, capabilities, retry policy and the lifecycle functions. This is the artifact you review and keep.

targets/ is the Target Repository. A target names an element and lists the ways to find it, in priority order, so a broken selector falls through instead of failing a run. Targets are grouped by domain (orders.targets.ts, auth.targets.ts) and each module is registered in targets/index.ts, which the resolver reads.

framework/ is a pure library with no side effects: the runner that drives the transaction lifecycle, the exception types, the retry policy, the structured logger, the run artifact layout and the workflow derivation that turns step calls into a diagram.

runtime/ is the Robot's side of the platform. It holds the automation registry, the credential providers, RobotService, the capability engines (excel-service, file-service, api-service, db-service, email-service, pdf-service, desktop-service), the tspkg packager and the AI generator under runtime/generator/.

robot/ contains one file, cli.ts, the thin executable that exposes list, run, run-package, package, show and generate. All behaviour lives in runtime/, so the same path can host the Robot in a service or a container later.

studio/ is the web IDE. server.mjs is the API that spawns the Robot per run, src/ is the React, TypeScript and Monaco front end, scripts/dev.mjs starts both halves and dist/ is build output.

orchestrator/ is the local Orchestrator service: the queue, the scheduler, environments, provisioning, deployments, the vault, the Action Centre and the CLI. The measure-*.ts files beside it are measurement scripts for individual behaviours, not part of the running service.

config/ holds tasksultan.config.ts, the single dependency-free module that defines the project root, the artifacts and data paths, the demo URL and retry policy plus the mailbox and Action Centre settings.

demo-app/ is the zero-dependency Node server the examples drive. It is an Order Processing app with a queue API, a login page and a seeded order set.

#Authoring and example directories

examples/ is the golden corpus the AI generator learns from: snapshots of the canonical automations and their targets. Regenerate it with npm run examples:sync after editing a canonical automation.

tools/ holds development tools: the automation conformance gate, the Excel seeders, make-artifact.ts for the authored path, sync-examples.ts, local-gate.mjs and the sample process briefs in tools/briefs/.

templates/ holds the re-package starter, a skeleton automation plus create.ts to instantiate it with a new id.

suites/ holds test suite definitions such as platform-smoke.json, which describes real automation runs and the evidence each one must produce.

tests/ is the Playwright Test suite. It runs real automations against the real demo app on ephemeral ports.

docs/ holds the design documents, specs, scope notes and verification records for the platform. It is engineering history, not the end-user documentation you are reading now.

evidence/ holds assembler.mjs, the caller-side tool that writes an evidence-manifest.json into a run's evidence directory with input and output fingerprints.

ops/ holds operator scripts: a pilot smoke test, a state backup and a restore-custody check.

#Generated and ignored directories

These are not source. A fresh clone either lacks them or rebuilds them.

• artifacts/ holds per-run evidence under artifacts/<id>/<runId>/ and generated packages under artifacts/tspkg/ and artifacts/generated/.
• data/ holds the Excel workbooks the Excel capability reads and writes, seeded by the demo:data, demo:orders and demo:customers scripts.
• test-results/ is Playwright Test output.
• node_modules/ is installed dependencies. In this checkout it is a symlink to a shared copy; a fresh clone builds its own.
• orchestrator/state/ is local service state.

#Top-level files and folders

package.json defines the scripts and the Node version floor. playwright.config.ts splits the heavy specs into a single-worker project. tsconfig.json sets strict mode and lists the source directories. README.md and AGENTS.md are the developer and agent contracts. .github/workflows/gate.yml is CI and .github also holds the boundary allowance lists. TaskSultan-Recorder.cmd launches the desktop recorder on Windows.

#Things that catch people out

• studio/dist/ and artifacts/ are build outputs. Editing them by hand is lost on the next build.
• docs/ is not the user documentation. It records how the platform was built and verified.
• A new targets module does nothing until you register it in targets/index.ts.
• The measure-*.ts files in orchestrator/ are excluded from the typecheck and are not imported by the service.