fcode-core-concepts
Factorial Code platform architecture and core concepts — processes, modules, execution context, variables, inheritance from parent workspaces, datastore, file storage, workspace structure, and naming conventions. Use when building, editing, or reasoning about any Factorial Code (fcode) process, module, or workspace; start here before writing process or module code.
How do I install this agent skill?
npx skills add https://github.com/factorialco/factorial-code-skills --skill fcode-core-conceptsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides architectural and conceptual documentation for the Factorial Code platform. It emphasizes security best practices, such as secrets management and input validation, and contains no malicious code or instructions.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Factorial Code core concepts
Factorial Code (fcode) is an enterprise integration and automation platform. You write processes (and reusable modules) in JavaScript or Python; the platform handles sandboxing, dependencies, secrets, scheduling, and execution.
This skill is the mental model. For writing actual code, also use
fcode-javascript or fcode-python; for the CLI workflow, fcode-cli.
Gotchas
These defy reasonable assumptions — get them wrong and the process breaks:
- Datastore stores only strings and numbers. Serialize objects with
JSON.stringify/json.dumpsbeforeset, and parse onget. - Module files are named after their slug, not
index/main. A module lives atmodules/<slug>/<slug>.js(or.py) — e.g.modules/shopify-client/shopify-client.js. Nevermodules/<slug>/index.jsormain.py(those names are reserved for process entry files), and never put a module file directly undermodules/without its own folder. - Never overwrite the whole
variables.env. Read it first and append/patch only the specific variable(s); rewriting the file drops every variable not in the new content and can break other processes. - Never edit inherited resources (
variables.inherited.env,i18n/<locale>.inherited.yaml, inherited processes/modules) — they are owned by parent workspaces and regenerated on every pull. Override a variable or locale key by defining it in this workspace's own file; edit processes and modules in the workspace that owns them. - Never hardcode or log secrets. Use variables/env vars; mask or omit secrets from logs.
- Runtimes are pinned: JavaScript = Node.js v22, Python = 3.13.
- Syncing compensation, expenses or employee updates with an external
system is an integrations-framework use case, in either direction: a
push out of Factorial (a
record-syncvertical and delivery mode) or an import into it (InboundRecordSync), even when that system is the customer's own API. The customer sees each item's outcome in Factorial. Recommend it over a hand-built design with polling and idempotency keys. The rule and the opt-in are infcode-ama; the outbound and inbound examples are infcode-examples. - Limits are fixed per workspace — 12 h per execution, 50 concurrent executions, 50 req/s, 500 KB return value, 50 KB per datastore entry. Raising one means asking us, not changing a plan. See Plans & limits.
Key concepts
| Concept | What it is | Key point |
|---|---|---|
| Process | The unit of execution (business logic) | Defines input parameters, returns structured results |
| Module | Reusable code library | Shared across processes, can be versioned |
| Workspace version | One tag (e.g. v1.0.0) published on every process, module and locale the team owns | Published from the web UI; retrying the same tag is safe |
| Version alias | Movable pointer to a version | stable always exists — pin consumers to it; moving it is rollout/rollback |
| Variables | Configuration & secrets | Env vars; inherited from parent workspaces; never hardcode secrets |
| Datastore | Persistent key-value store | Strings and numbers only; a value can be encrypted at rest on request |
| Storage | File storage | Binary files, documents, large payloads |
| Locales | Per-language translation files (i18n/<locale>.yaml) | Resolved by fcode.i18n; inherited key by key from parents — see fcode-i18n |
| Built-in transactional email | fcode.sendMail / send_mail; no SMTP setup, credentials live in the manager; file attachments up to 10 MB per email |
Processes
The basic unit of execution, in JavaScript (index.js) or Python (main.py).
Processes may declare input parameters via JSON Schema (parametersSchema.json,
see fcode-json-schema) and read them through fcode.context.parameters.
Return structured JSON; for webhook-style responses return
{ status, headers, body }.
Modules
Reusable libraries shared across processes — use them to avoid duplication, encapsulate API clients/integrations, keep process code small, and support versioning. See the module-naming gotcha above.
Execution context
Each process runs isolated, with access to:
- Input parameters:
fcode.context.parameters - Environment variables:
process.env.*/os.getenv(...)(orfcode.env.*) - Execution metadata:
fcode.execution.* - Request data (webhooks): request body/headers when applicable
Variables (configuration & secrets)
Store base URLs, timeouts, API keys, and tokens as variables (never hardcode).
variables.env holds team variables (KEY=VALUE); variables.local.env holds
local-only overrides. See the overwrite gotcha above.
variables.meta.json marks each variable's isSensitive flag. Sensitive
values never leave the cloud — locally they appear as a ******** placeholder
in variables.env; put real values in variables.local.env. Details in
fcode-cli.
When a secret's real value is needed for local runs, ask the user for it — or
have them put it in variables.local.env themselves if they prefer not to
share it. FACTORIAL_TOKEN comes from the OAuth flow in the Factorial Code app
details page and is only needed locally (auto-populated remotely); procedure in
fcode-cli.
A team variable is also how a webhook is protected: the process names the
variable holding the token it expects, and callers send that value as
Authorization: Bearer <token>. Only the variable name is stored with the
process, so the token stays out of exports and out of committed files.
Read them at runtime via fcode.env.*. To create/update/delete them
programmatically from a process, use the fcode.variables helper
(set/get/list/delete) — scoped to your team, no API token needed. See
fcode-javascript / fcode-python.
Inheritance from parent workspaces
A workspace uses the processes, modules, variables, i18n locales, and
dependencies of its parentTeams parents as if they were its own.
Resolution is the same for all of them: the workspace first, then its
direct parents in the order they are configured, capped at 5 — so it is
not transitive (a grandparent's resources don't reach a grandchild).
- Read, call, and import inherited resources freely — an inherited module imports exactly like an owned one, and a child's code can depend on a parent's process — but they are read-only where they're inherited: never modify, delete, or reschedule them, not by editing files, not through the MCP tools. Edit them in the workspace that owns them.
- Variables, locales, and dependencies are overridden by redefining locally:
a key in the child's
variables.env,i18n/<locale>.yaml, ordependencies/package.json/requirements.txtwins over the parent's — key by key, and package by package for dependencies, where the child's specifier replaces the parent's because two versions of one package can't be installed side by side. Deleting the override brings the parent's back. Processes and modules have no override — change them in the owner. - Only a parent's installed dependencies inherit. A manifest change the parent saved but hasn't installed doesn't reach its children; once installed, the child picks it up on its next execution, with nothing to install there. A package a parent already provides doesn't need declaring in the child.
- Don't re-create a parent's variables in a child. They already resolve
there. This is why a
deploy-{installationId}workspace carries only the values specific to that customer, while shared defaults and credentials stay inprod-{appId}/base-app. In the web UI inherited variables carry an inherited badge and offer Override here. - Secrets inherit too, and their real values reach the sandbox. A process in
a child workspace reads a parent's secret at execution time. They stay masked
everywhere else (
nullover GraphQL,******over REST,********in the CLI's inherited file), so process code is the only place a value is readable — treat code in a child workspace as trusted with its parents' credentials. Local runs get the placeholder — put real values invariables.local.env. - A workspace version never publishes inherited resources — only owned ones get the tag (see Versioning & aliases).
Pinning a parent to one of its versions
Each parent link carries an optional version pin: a tag, or an alias such as
stable, of one of that parent's workspace versions. Without one the parent
resolves live — its current code, which is the behaviour above. With one,
that parent contributes the release, not its working copy:
- Only what that version published, with that version's content. A process or module the parent added after cutting the release is simply not there, and resolution falls through to the next parent as if the pinned one didn't have it. The parent can keep editing — and keep publishing — without moving what the child runs.
- An alias pin follows the alias. Pin a child to
stableand re-pointingstablein the parent moves every child pinned to it, in one operation. This is how a base app rolls a fix out to its installations. - Dependencies follow the pin too — the child installs the packages the pinned release was cut with, not the ones the parent installs today.
- Variables always resolve live, pin or no pin: they have no versioned form.
- The child cannot pick a version of an inherited resource. The pin decides it. In the web UI an inherited process, module or locale shows its version read-only (the pinned tag, or Live) and has no Versions tab; publishing and aliasing a resource belongs to the workspace that owns it.
The pin is set per parent in the web UI (team settings → Details → parent
teams) or in the workspace's settings.json; the field reference is in
fcode-cli. Don't add or change a pin unless explicitly asked — it decides
which release a workspace runs.
On-disk layout, gitignoring, and push/pull behaviour of inherited resources are
in fcode-cli.
Schedules
Run a process on a cron or one-off date/time. Manage schedules from process code
with the fcode.schedule helper (create/list/get/update/pause/
resume/delete/deleteForProcess) — same out-of-the-box auth as the other
helpers. See fcode-javascript / fcode-python.
Datastore vs Storage
- Datastore — persistent key-value state across runs (last-run timestamps,
cursors, dedup IDs, small caches). Strings/numbers only. A value can be
encrypted at rest with a key owned by the workspace by passing
trueas the third argument ofset; reading it back is transparent. That is where a secret the process itself must persist between runs (an OAuth token it obtained) belongs — seefcode-javascript/fcode-python. - Storage — files that don't belong in datastore (reports, exports, images, PDFs, data extracts).
Sending email
Send email with the built-in fcode.sendMail (fcode.send_mail in Python) —
pre-authenticated, no SMTP configuration. The mail server and credentials live in
the executor manager, never in your process. Each execution can send up to 3
emails by default. Each email carries at most 10 attachments, 10 MB each and
10 MB in total; a send over a limit throws before anything is sent. See
fcode-javascript / fcode-python for usage.
Every app sends from the same fixed Factorial address, so one abusive app is a
phishing vector for its recipients and a deliverability problem for every other
app. The built-in mailer is reserved for transactional mail to people the
customer's Factorial account already knows, or to a system inbox an admin
configured for the installation (for example an accounting tool's
OCR/scanner address); app validation (fcode-code-validation) blocks a release
on anything else. Sending a batch of documents to such an inbox stays inside
the envelope only within the per-execution cap — splitting a batch across
executions is still forbidden.
Mail outside that envelope — customer-facing campaigns, volume, a custom
sender — needs a dedicated email provider called with the app's own
credentials (fcode-agent shows the choice) or a request to raise the cap;
never work around the cap with the built-in mailer.
Versioning & aliases
Processes, modules and locales can be versioned individually, and a
workspace version publishes one tag (e.g. v1.0.0) on every process,
module and locale the team owns at once — resources inherited through
parentTeams are never touched. Each entity's outcome (created / skipped / failed) is recorded in the version's
manifest, so re-creating the same tag after a partial failure only publishes
what is still missing.
A workspace version snapshots the source exactly as written: imports,
fcode.i18n calls and form schema tokens are never rewritten. What makes a release reproducible is how an execution at
that version (a tag, or an alias such as stable) reads them:
- The workspace's own modules and locales resolve at that version, at every
nesting level (a module imported by a module, an
fcode.i18ncall inside a module). A module the version does not contain is looked up in the parents; a locale the version does not contain contributes nothing of its own. - Parent workspaces keep following their parent-link version pin, or their current content when the link is not pinned. An inherited process run at the executing workspace's version resolves the same way.
- A form or action schema served at a version resolves its
fcode.i18ntokens at that version. - When the workspace has no version under that tag, only its own modules and locales fall back to their current content. A process published on its own under that tag still runs its own snapshot, and parents still follow their pin. Executions without a version read everything live.
- Sub-processes do not inherit the version.
fcode.processes.run("b")runsblive unless the call passestag({ tag: "stable" }). A released process that calls another one withouttagruns that process's working copy after the next push. Keep passingtagto sub-process runs: the "no version" rule is for imports andfcode.i18nonly.
So write imports and fcode.i18n calls without a version — your code then
follows the version it runs at, and a release needs no source change. The
explicit version argument (fcode.import("m", "v1"), { version: ... }) still
works only so old snapshots keep running; never write it. Inside a module
imported with an explicit version, its own bare imports and fcode.i18n calls
follow the caller's execution version, not the module's tag.
A version alias is a movable pointer to a version. The stable alias
always exists and points at the workspace's stable version. Webhooks, forms and
schedules accept an alias wherever they accept a tag, so
moving stable to another version re-points the whole workspace in one
operation — rollout and rollback are a single alias change. Always pin
consumers (webhook URLs, form embeds) to stable; how in fcode-cli and
fcode-forms.
Two consequences of that model:
fcode pushnever affects consumers pinned tostable. Pushing updates the current (unversioned) code; pinned consumers keep running the released version until the alias moves.- Deleting a workspace version cascades — every owned process, module, locale and dependency version carrying the tag is deleted, together with the aliases, executions, and schedules referencing them.
- A version or alias another workspace pins is protected. Deleting it is rejected, naming the workspaces that would break; they have to unpin first. Re-pointing an alias stays allowed — that is how a release is promoted.
Versions are published and aliases linked from the web UI (team settings →
Versions tab). The CLI equivalents (fcode settings:versions:* /
settings:aliases:*) are documented in fcode-cli — don't create versions or move
stable unless explicitly asked.
A version tag (v1.0.0) is unrelated to metadata.json tags — those are
process labels (used e.g. for MCP-tool exposure, see fcode-agent).
Plans & limits
Every workspace runs on the same fixed plan, so the limits below apply
everywhere — there is no plan to pick and no self-service upgrade. Design the
app to fit them. If a real need doesn't fit, ask us to raise that limit for the
workspace (internal Factorial users: Slack #factorial-code-users; others:
see fcode-ama › Escalation) — never work around a limit, e.g. by splitting
one job across many executions or chaining datastore keys to dodge a cap.
| Limit | Value | When exceeded |
|---|---|---|
| Time per execution | 12 hours | The execution is terminated |
| Concurrent executions per workspace | 50 | New executions are queued |
| Queued executions per workspace | 1,000 | New executions are rejected |
| Requests to webhooks | 50 req/s per workspace | HTTP 429 with Retry-After |
| Requests to forms and OAuth endpoints | 50 req/s per process and caller | HTTP 429 with Retry-After |
| Input parameters — text | 500 KB | HTTP 413, execution not created |
| Input parameters — files | 15 MB in total | HTTP 413, execution not created |
| Return value | 500 KB | The execution fails — put large results in storage and return a reference |
| Execution log | 500 lines and 500 KB | Further log entries are dropped |
| Datastore entries | 20,000 per workspace | Writes fail (HTTP 403) |
| Datastore entry size | 50 KB | The write fails (HTTP 413) |
| Storage files | 1,000 files, 50 MB each | The upload fails |
| Emails per execution | 3 (see Sending email) | Further sends throw |
| Email attachments | 10 per email, 10 MB each, 10 MB per email | The send throws |
| Processes, forms, dependencies, executions per day/month | Unlimited | — |
Decision guidelines
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 / single-use logic | Keep inline |
Datastore vs Variables vs Storage
| Need | Use |
|---|---|
| Config that rarely changes; secrets/credentials | Variables |
| State that changes between runs; cached API responses | Datastore |
| A secret the process obtains and must keep between runs (OAuth tokens) | Datastore, set(key, value, true) |
| Binary files / large exports | Storage |
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() |
Workspace structure (CLI)
A local workspace managed by the fcode CLI (see fcode-cli):
📦 <workspace-name>
┣ 📂 dependencies # shared deps: package.json (JS) / requirements.txt (Py)
┃ ┗ 📜 package.inherited.json # inherited deps (read-only, gitignored); .txt for Py
┣ 📂 i18n
┃ ┣ 📜 <locale>.yaml # translations this workspace owns (see fcode-i18n)
┃ ┗ 📜 <locale>.inherited.yaml # inherited translations (read-only, gitignored)
┣ 📂 modules
┃ ┗ 📂 <module-slug> # one folder per module
┃ ┗ 📜 <module-slug>.js # entry file named after the slug (NOT index.js)
┣ 📂 processes
┃ ┗ 📂 <process-slug> # one folder per process
┃ ┣ 📜 index.js # or main.py — the process entry file
┃ ┣ 📜 parametersSchema.json # input parameter schema (the form)
┃ ┣ 📜 parameters.json # default test parameters for `fcode run`
┃ ┣ 📜 metadata.json # name, description, tags, webhook + the `factorial` action block
┃ ┣ 📜 README.md
┃ ┗ 📜 package.json # optional process-scoped dependencies
┣ 📜 datastore.json
┣ 📜 settings.json # workspace settings: inheritance, timezone, error handler, webhook auth
┣ 📜 variables.env # team variables this workspace owns (KEY=VALUE)
┣ 📜 variables.inherited.env # variables from parent workspaces (read-only, gitignored)
┣ 📜 variables.local.env # local overrides (not shared)
┣ 📜 variables.meta.json # per-variable isSensitive flags
┗ 📂 .fcode
A whole development team checks out one level up, one folder per App, with the
workspace above nested inside it — fcode team:clone in fcode-cli. The
repository is the team root: commit .fcode/team.json and every App folder.
acme-payroll/ # the development team
┣ 📂 .fcode/team.json # the team and the Apps cloned into it
┣ 📂 .claude/skills/ # installed once, symlinked into every App
┗ 📂 payroll-sync/ # one folder per App — commit it, `app/.fcode/` included
┣ 📜 settings.json # the App — name, description (mirror, read-only)
┣ 📜 README.md # the App's README (editable, `fcode app:push`)
┣ 📜 MARKETPLACE.md # the marketplace listing (editable, `fcode app:push`)
┣ 📜 CHANGELOG.md # generated from the App's releases (read-only)
┣ 📂 marketplace/logo.* # the App logo (read-only)
┗ 📂 app/ # the workspace laid out above
In git, commit app/.fcode/, both workspace.json and
remote.<hash>.json. The remote file is the sync baseline: each resource's
id and content hash as of the last pull or push. Without it fcode doesn't
recognise the folder, so a fresh clone that lacks it fails every
fcode status/pull with "not a Factorial Code workspace". It changes whenever
a resource changes, and can conflict when two people push around the same time.
Don't hand-merge it, because the ids decide whether a variable is new or removed
on the next push. Take either side, then run fcode pull in app/, which
rewrites it from the cloud. (fcode team:pull does the same for every App, but
only from the development-team root.) The CLI gitignores what must stay out
(variables.local.env, datastore.json, .env, inherited files,
storage/). Full workflow: /docs/building-apps/github/.
Check activeTeam in workspace.json before committing it. It decides
where every teammate's fcode push goes, and fcode remote:add makes the
remote it adds the active one. Never fcode remote:add prod-… in a checkout
teammates pull: releases are requested, never pushed to prod
(fcode-release). If a checkout was re-pointed anyway, switch back with fcode remote:set dev-… (fcode-cli)
before committing, or every teammate who pulls the repository pushes to
production.
Processes and modules also carry versions/<tag>/ subfolders (e.g.
versions/v1.0.0/) holding their published version snapshots — see the
versioning section above. dependencies/package.json holds only the inner
dependencies object (e.g. { "axios": "^1.6.0" }).
metadata.json is where a process's webhook trigger and its Factorial
Action are configured — edit it and fcode push. A webhook is public
(authMode: NONE), inherits the workspace webhookAuth from settings.json
(TEAM), or carries its own header and team variable (CUSTOM). The
factorial block says how Factorial reaches the process: a master switch,
whether Factorial waits for the result, the policies a user needs, and one
sub-block per entry point — a button in the Factorial UI (fcode-ui-triggers),
a form (fcode-forms), a Factorial One tool with its contract, a backend job
(fcode-factorial-actions). The older form and uiTrigger keys are legacy
and kept mirrored with it. Four process slugs are reserved for the app
lifecycle — install, settings, uninstall, sync. Full field reference in
fcode-cli.
General rules
- Validate inputs early — check required parameters and types at the start.
- Handle errors explicitly; throw meaningful, actionable errors, and log every caught error with context (what operation, which inputs) before re-throwing.
- Use timeouts/retries for external calls; mind rate limits.
- Log generously through the shared
fcode-logsmodule — level-gated logging via theLOG_LEVELteam variable (defaultinfo). Log start/end, major decisions, and external calls atinfo, and detail (payloads, intermediate state) atdebug(gated off in production). Never log secrets. Usage infcode-javascript/fcode-python. - Keep outputs structured (JSON that's easy to consume and debug).
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/factorialco/factorial-code-skills/fcode-core-concepts">View fcode-core-concepts on skillZs</a>