# YepCode Core Concepts Rules

> Essential guide to YepCode platform architecture and core concepts. Covers processes, modules, execution context, team variables, datastore, workspace structure, and development best practices for building enterprise-grade integrations and automations.

Essential guide to YepCode platform architecture and core concepts. Covers processes, modules, execution context, team variables, datastore/storage, workspace structure, and best practices for building robust integrations and automations.

[Download this file](/docs/ai-rules.md)

## What is YepCode?

[Section titled “What is YepCode?”](#what-is-yepcode)

YepCode is an enterprise-ready integration and automation platform that offers comprehensive features for API integrations, workflow automation, and data processing. It excels in providing enterprise-grade sandboxing and security measures specifically designed for running code generated by LLMs.

This offers developers a familiar coding environment, while handling all the infrastructure concerns, security measures, and dependency management automatically.

## Quick Reference

[Section titled “Quick Reference”](#quick-reference)

### Key Concepts at a Glance

[Section titled “Key Concepts at a Glance”](#key-concepts-at-a-glance)

| Concept       | Description                       | Key point                                 |
| ------------- | --------------------------------- | ----------------------------------------- |
| **Process**   | Executable unit of business logic | Has input parameters, returns results     |
| **Module**    | Reusable code library             | Shared across processes, can be versioned |
| **Variables** | Configuration & secrets           | Use env vars; never hardcode secrets      |
| **Datastore** | Persistent key-value store        | **Strings and numbers only**              |
| **Storage**   | File storage                      | Use for binary files and documents        |

### Runtime Versions

[Section titled “Runtime Versions”](#runtime-versions)

| Language       | Runtime     |
| -------------- | ----------- |
| **JavaScript** | Node.js v22 |
| **Python**     | v3.13       |

## Core Concepts

[Section titled “Core Concepts”](#core-concepts)

### Processes

[Section titled “Processes”](#processes)

* **What it is**: The basic unit of execution in YepCode.
* **Languages**: JavaScript (Node.js v22) or Python (v3.13).
* **Parameters**: Processes may define input parameters via JSON Schema (`parametersSchema.json`) and access them through `yepcode.context.parameters`.
* **Return values**: Return structured JSON for results; for webhook-style responses, return `{ status, headers, body }` when applicable.

### Workspace Structure (CLI)

[Section titled “Workspace Structure (CLI)”](#workspace-structure-cli)

If you use the YepCode CLI, your local workspace commonly looks like this:

```plaintext
  📦 <workspace-name>
  ┣ 📂 dependencies
  ┃ ┣ 📜 package.json
  ┃ ┣ 📜 requirements.txt
  ┣ 📂 modules
  ┃ ┣ 📂 <javascript-module-slug>
  ┃ ┃ ┗ 📜 <module-slug>.js
  ┃ ┣ 📂 <python-module-slug>
  ┃ ┃ ┗ 📜 <module-slug>.py
  ┃ ┣ 📂 <module-with-versions>
  ┃ ┃ ┣ 📂 versions
  ┃ ┃ ┃ ┣ 📂 v1.0
  ┃ ┃ ┃ ┃ ┗ 📜 <module-slug>.js
  ┃ ┃ ┃ ┗ 📂 ...
  ┃ ┃ ┗ 📜 <module-slug>.js
  ┃ ┗ 📂 ...
  ┣ 📂 processes
  ┃ ┣ 📂 <javascript-process-slug>
  ┃ ┃ ┣ 📜 README.md
  ┃ ┃ ┣ 📜 index.js
  ┃ ┃ ┣ 📜 parametersSchema.json
  ┃ ┃ ┣ 📜 parameters.json
  ┃ ┃ ┗ 📜 package.json (process scoped dependencies)
  ┃ ┣ 📂 <python-process-slug>
  ┃ ┃ ┣ 📜 README.md
  ┃ ┃ ┣ 📜 main.py
  ┃ ┃ ┣ 📜 parametersSchema.json
  ┃ ┃ ┣ 📜 parameters.json
  ┃ ┃ ┗ 📜 requirements.txt (process scoped dependencies)
  ┃ ┣ 📂 <process-slug-with-versions>
  ┃ ┃ ┣ 📂 versions
  ┃ ┃ ┃ ┣ 📂 v1.0
  ┃ ┃ ┃ ┃ ┣ 📜 README.md
  ┃ ┃ ┃ ┃ ┣ 📜 index.js
  ┃ ┃ ┃ ┃ ┣ 📜 parametersSchema.json
  ┃ ┃ ┃ ┃ ┗ 📜 parameters.json
  ┃ ┃ ┃ ┗ 📂 ...
  ┃ ┃ ┣ 📜 README.md
  ┃ ┃ ┣ 📜 index.js
  ┃ ┃ ┣ 📜 parametersSchema.json
  ┃ ┃ ┗ 📜 parameters.json
  ┃ ┗ 📂 ...
  ┣ 📜 datastore.json
  ┣ 📜 variables.env
  ┣ 📜 variables.local.env
  ┣ 📜 .gitignore
  ┗ 📂 .yepcode
```

Key folders/files:

* **`dependencies/`**: Shared dependencies source configuration.

  * **`package.json`**: JavaScript dependencies (the inner `dependencies` object only). Example:

    ```json
    {
      "axios": "^1.6.0",
      "nodemailer": "^6.9.0"
    }
    ```

* **`requirements.txt`**: Python dependencies. Example:

  ```txt
  datarobot==3.5.2
  psycopg2-binary==2.9.10
  ```

* **`processes/`**: One folder per process (code, parameters schema, test parameters, README).

* **`modules/`**: One folder per module (reusable libraries).

* **`variables.env`**: Team variables in `.env` format (`KEY=VALUE`).

* **`variables.local.env`**: Local overrides (not shared).

* **`datastore.json`**: Datastore contents (if exported by tooling).

### Modules

[Section titled “Modules”](#modules)

Modules are reusable code libraries shared across processes. Use modules to:

* Avoid duplication (DRY)
* Encapsulate API clients / integrations
* Keep process code small and readable
* Support versioning for stable interfaces

**Module file naming (required):** Each module must live in a folder named after the module slug, with the entry file named the same: `modules/<module-slug>/<module-slug>.js` (JavaScript) or `modules/<module-slug>/<module-slug>.py` (Python). Do **not** use `index.js` or `main.py` for modules—those names are only for process entry files. Example: `modules/shopify-client/shopify-client.js` ✅; `modules/shopify-client/index.js` ❌.

### Execution Context

[Section titled “Execution Context”](#execution-context)

Each process runs in an isolated environment and has access to:

* **Input parameters**: `yepcode.context.parameters`
* **Environment variables**: `process.env.*` / `os.getenv(...)` (or `yepcode.env.*`)
* **Execution metadata**: `yepcode.execution.*`
* **Request data** (webhooks): request body/headers (when applicable)

### Variables (Configuration & Secrets)

[Section titled “Variables (Configuration & Secrets)”](#variables-configuration--secrets)

* Store configuration (base URLs, timeouts) and secrets (API keys, tokens) as variables.
* **Never hardcode secrets** in code or commit them to source control.
* **Never log secrets** (mask or omit them from logs).
* When editing variable files (e.g. `variables.env`), **do not overwrite the entire file** when adding or updating a variable. Read the file first and add or update only the specific variable(s) so existing variables are not removed.

### Datastore

[Section titled “Datastore”](#datastore)

Datastore is a persistent key-value store for maintaining state across runs.

* **Great for**: last-run timestamps, cursors, deduplication IDs, caches.
* **Critical limitation**: can only store **strings** and **numbers**. Serialize objects to JSON first.

### Storage

[Section titled “Storage”](#storage)

Storage is for files (binary or large payloads) that don’t belong in datastore.

* **Great for**: reports, exported files, images, PDFs, data extracts.

## Decision Guidelines

[Section titled “Decision Guidelines”](#decision-guidelines)

### When to Create a Module vs Inline Code

[Section titled “When to Create a Module vs Inline Code”](#when-to-create-a-module-vs-inline-code)

| Scenario                              | Recommendation                      |
| ------------------------------------- | ----------------------------------- |
| API client used by multiple processes | ✅ Create a module                   |
| Utility helpers used 2+ times         | ✅ Create a module                   |
| One-off transformation                | ❌ Keep inline                       |
| Complex logic only used once          | ❌ Keep inline (unless it will grow) |

### When to Use Datastore vs Variables vs Storage

[Section titled “When to Use Datastore vs Variables vs Storage”](#when-to-use-datastore-vs-variables-vs-storage)

| Need                              | Use                           |
| --------------------------------- | ----------------------------- |
| Configuration that rarely changes | **Variables**                 |
| Secrets / credentials             | **Variables**                 |
| State that changes between runs   | **Datastore**                 |
| Caching API responses             | **Datastore** (mind size/TTL) |
| Binary files / large exports      | **Storage**                   |

## Naming Conventions

[Section titled “Naming Conventions”](#naming-conventions)

| Resource             | Convention             | Example              |
| -------------------- | ---------------------- | -------------------- |
| Process slug         | kebab-case             | `order-sync-shopify` |
| Module slug          | kebab-case             | `shopify-client`     |
| Variables            | SCREAMING\_SNAKE\_CASE | `SHOPIFY_API_KEY`    |
| JavaScript functions | camelCase              | `fetchOrders()`      |
| Python functions     | snake\_case            | `fetch_orders()`     |

## General Rules (Always Follow)

[Section titled “General Rules (Always Follow)”](#general-rules-always-follow)

* **Validate inputs early**: check required parameters and types at the start.
* **Handle errors explicitly**: throw meaningful, actionable errors.
* **Use timeouts/retries** for external calls; be mindful of rate limits.
* **Log key steps** (start/end, major decisions, external calls) but **never log secrets**.
* **Avoid hardcoded values**: prefer parameters or variables.
* **Keep outputs structured**: return JSON that is easy to consume and debug.