Skeleton structure

The Orchesty project skeleton is the meta-repository for a full-stack Orchesty deployment. It ships the platform configuration and reserves a single subfolder, worker/, for your code. Everything else is owned by Orchesty and updated by pulling new skeleton releases.

For a side-by-side concept of where the worker fits in the architecture, see Concepts: Architecture.

Top-level layout #

my-orchesty/
  docker-compose.yml       # platform services (Admin UI, backend, Mongo, RabbitMQ, worker)
  Makefile                 # init-dev, docker-up-force, docker-stop, docker-down-clean
  AGENTS.md                # setup workflow for AI editors (Cursor, Claude Code, ...)
  .env.dist                # template environment (secrets, DEV_IP, UID/GID)
  .env                     # generated by `make init-dev`, gitignored
  worker/                  # YOUR CODE GOES HERE (Node.js)
  topology/                # exported topology JSON definitions (versioned with code)
  README.md                # skeleton README, kept in sync with the repo

You own:

• worker/ and everything inside it.
• topology/ (export from the Admin UI when you want a deployable record).
• .env (after make init-dev).

You don't edit:

• docker-compose.yml (platform definition; pull updates from upstream).
• Makefile (helper targets owned by the skeleton).
• .env.dist (template; copy to .env and edit there).
• AGENTS.md (setup workflow for AI agents; updated with the skeleton).

Inside worker/ #

The worker subfolder follows the same structure as the worker-only starter:

worker/
  src/
    index.ts               # entry: register applications, connectors, batches
    MyService/
      MyServiceApplication.ts
      Connector/
        MyServiceGetResource.ts
      Batch/
        MyServiceListResources.ts
      CustomNode/
        MyMapper.ts
      __tests__/
        MyServiceGetResource.ts
        Data/
          MyServiceGetResource/
            input.json
            output.json
            mock.json
  Dockerfile               # worker image
  docker-compose.yaml      # standalone compose for worker container ops
  Makefile                 # install, start, lint, unit, test
  package.json             # @orchesty/nodejs-sdk + @orchesty/nodejs-ai (dev)
  tsconfig.json
  .env.dist                # template; .env is generated on first run

Conventions #

• One folder per third-party service. Group all classes for Hubspot under worker/src/Hubspot/. The conventions live in Naming rule.
• One Application class per service. All connectors and batches register against it via container.setNode(node, app).
• Tests in __tests__/ next to the source. Fixtures live under Data/<NodeName>/.
• Topology JSON in topology/. Export from the Admin UI once a topology is stable; this is your deployable artifact.

Adding a new integration #

1. Create a folder worker/src/<Service>/.
2. Add <Service>Application.ts.
3. Add connector(s) and/or batch(es) under <Service>/Connector/ and <Service>/Batch/.
4. Register everything in worker/src/index.ts.
5. Restart the worker; the new nodes appear in the Admin UI's editor.

See also #

• Local dev loop — running the skeleton day to day.
• Building nodes / Custom nodes
• Authentication and settings