File and folder structure

When you clone a collection module from Root, use the generated project tree to find configuration, source code, tests, and legacy workflow files.

Project tree

my-collection-module/
├── .root-auth
├── .root-config.json
├── .gitignore
├── README.md
├── package.json
├── tsconfig.json
├── code/
│   ├── main.ts
│   ├── lifecycle-hooks.ts
│   ├── webhook-hooks.ts
│   ├── config.ts
│   ├── env.ts
│   ├── env.sample.ts
│   ├── adapters/
│   ├── clients/
│   ├── controllers/
│   │   ├── root-event-processors/
│   │   └── <provider>-event-processors/
│   ├── interfaces/
│   ├── types/
│   ├── utils/
│   └── unit-tests/
└── workflows/
    └── manual-transactions/
        └── <transaction-key>.json

Most day-to-day changes happen in code/ and .root-config.json. Legacy manual transactions use workflows/.

Find the right file for common tasks

Task	Start here
Add logic after a policy lifecycle event	`code/lifecycle-hooks.ts`
Handle a payment provider webhook	`code/webhook-hooks.ts`
Add provider-specific webhook processing	`code/controllers/<provider>-event-processors/`
Map provider data into Root data	`code/adapters/`
Configure API keys or base URLs	`code/config.ts` and `code/env.ts`
Add a legacy manual transaction	`.root-config.json` and `workflows/manual-transactions/<transaction-key>.json`
Add or update unit tests	`code/unit-tests/`

Configuration file

.root-config.json stores the collection module's identity and platform settings, including the module key, display name, organisation ID, host, runtime stack, and optional manual transaction declarations.

For the full property reference, see Collection module settings.

File and folder reference

Do not commit .root-auth. It contains the API key used by rp pull and rp push.

Path	Purpose
`.root-auth`	Stores your Root API key as `ROOT_API_KEY=<your API key>`. `rp clone` creates this file and `.gitignore` excludes it. If it is missing, create it with a valid API key issued under the organisation that owns the collection module. Use sandbox keys for local development; switch to production keys only when intentionally operating against production.
`README.md`	Optional project notes for developers, such as what the product is, client and insurer details, related file links, maintainers, contributors, and outstanding tasks.
`code/`	The collection module source code. Collection modules are written in TypeScript, and the compiled output is bundled into a single AWS Lambda deployment package on `rp push`. `tsconfig.json` configures type checking and editor IntelliSense.
`code/main.ts`	The module entry point. Re-exports lifecycle and webhook handlers so the platform can locate them at runtime.
`code/lifecycle-hooks.ts`	Policy lifecycle event handlers. Add exports here for the Root lifecycle events your collection module needs to handle. See Root lifecycle events.
`code/webhook-hooks.ts`	Contains `processWebhookRequest`, which handles inbound webhook requests — typically from your payment provider, such as Stripe.
`code/config.ts`	Centralises environment-specific values such as API keys and base URLs so the rest of the code does not branch on environment. See Collection module environments.
`code/env.ts` and `code/env.sample.ts`	`env.ts` exposes typed environment variables to the module. `env.sample.ts` is a committed template documenting which variables are expected. Copy it to `env.ts`, or your secret-store equivalent, when setting up locally.
`code/controllers/`	Per-event handler implementations. `root-event-processors/` handles Root lifecycle events, and `<provider>-event-processors/` handles payment provider webhook events, such as `stripe-event-processors/`.
`code/adapters/`	Translation layer between provider-shaped data and Root-shaped data, for example mapping a Stripe `PaymentIntent` to a Root payment.
`code/clients/`	Wrappers around external SDKs and HTTP clients, kept in one place so they can be configured uniformly via `config.ts`.
`code/interfaces/`	Module-owned TypeScript interfaces and type aliases used across the module.
`code/utils/`	Reusable helpers that do not belong in a specific controller or adapter.
`code/types/` and `code/unit-tests/types/`	Root platform type declarations (`.d.ts`) for objects passed into hooks. They support TypeScript checking, editor IntelliSense, and unit-test scaffolding.
`code/unit-tests/`	Unit tests for your module, runnable via `rp test`.
`workflows/`	Legacy manual transaction definitions. Each JSON file under `workflows/manual-transactions/` must match an entry in `.root-config.json`'s `manualTransactions` array.

Other files

.gitignore — ensures .root-auth (your API key) and other local-only files are never committed.
package.json / tsconfig.json — Root-managed Node.js and TypeScript project configuration. rp clone and rp pull keep these in sync with expected dependencies and compiler options.

Project tree

Find the right file for common tasks

Configuration file

File and folder reference

Other files

Related guides