YepCode Core Concepts Rules

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

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

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

Language	Runtime
JavaScript	Node.js v22
Python	v3.13

Core Concepts

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)

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

  📦 <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:
```
{
  "axios": "^1.6.0",
  "nodemailer": "^6.9.0"
}
```
requirements.txt: Python dependencies. Example:
```
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

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

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)

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).

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

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

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

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

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.