Skip to content

DOCS.md

Latest commit

 

History

History
134 lines (91 loc) · 2.76 KB

DOCS.md

File metadata and controls

134 lines (91 loc) · 2.76 KB

DOCS

Generic technical documentation for Stockflow.

Scope

This document is intentionally scoped to:

  • stockflow/
  • root config used by Stockflow (docker-compose.yml, .env, config/)

Excluded by default:

  • temporal/
  • bpm_engine/

Concept

Stockflow is a YAML execution engine for backend workflows.

Project direction:

  • Inspired by Kestra and Supabase.
  • Built so users can define workflow logic in YAML and execute it safely in a controlled runtime.

Main User Flow

  1. Create PostgreSQL tables.
  2. Run db:generate from stockflow/package.json.
  3. Stockflow updates generated DB artifacts used by the project.
  4. Write YAML functions in stockflow/data/functions.
  5. Execute them through /api/rpc.

Quick Start

Run with Docker

docker compose up

Run Stockflow locally

cd stockflow
npm install
npm run dev

API Summary

Stockflow server entrypoint: stockflow/src/index.ts

  • GET /api: service check endpoint
  • POST /api/rpc: execute YAML function
  • POST /api/query: execute structured query model
  • POST /mcp: MCP endpoint exposing YAML tools with skill: true

YAML Function Model

Location: stockflow/data/functions/**/*.yml

Common structure:

  • name
  • version
  • temporal (optional)
  • params
  • steps
  • return

Temporal routing rules:

  • Top-level temporal: true applies to all steps by default.
  • step.temporal overrides the default for an individual step.
  • Flagged steps are sent to TEMPORAL_STEP_EXECUTOR_URL when configured.
  • Without TEMPORAL_STEP_EXECUTOR_URL, flagged steps run locally for backward compatibility.

Supported step.type values:

  • call
  • map
  • editField
  • reference
  • query
  • persist
  • condition
  • loop

Runtime + Data Layer

  • Runtime executor: stockflow/src/runtime/index.ts
  • Built-in functions: stockflow/src/runtime/system-functions.ts
  • YAML loader + templating: stockflow/src/helper/yaml.loader.ts
  • Query compiler: stockflow/src/helper/query.model.ts
  • DB schema: stockflow/src/db/schema.ts

Auth and RLS

Request context is converted into PostgreSQL claim settings in middleware:

  • stockflow/src/middleware/rls.ts
  • stockflow/src/middleware/withDb.ts

Typical headers:

  • x-claims
  • x-auth-request-user
  • x-user-role
  • authorization: Bearer <jwt>

Migrations

cd stockflow
npm run db:generate
npm run db:migrate

Environment

Minimum expected variables:

  • DATABASE_URL
  • JWT_SECRET

Optional platform variables may include OAUTH2_PROXY_*, N8N_*, and pgAdmin settings depending on compose usage.

Contribution Notes

  • Keep changes scoped and minimal.
  • Preserve existing YAML runtime behavior unless change is intentional.
  • Avoid committing secrets.
  • Update docs when endpoint/runtime behavior changes.