Skip to main content

Guides and FAQs

This section provides answers to common questions and step-by-step guides for using the Godspeed Meta-Framework. It covers essential topics including setting up and securing APIs (REST, CRUD, Swagger, Postman, JWT, OAuth2), writing business logic using workflows and functions (TypeScript and Javascript), and accessing various datasources like databases, APIs, and caches.

What is Godspeed?​

Godspeed is a 4th generation declarative microservice framework for Node.js that simplifies backend development. It emphasizes configuration-over-code, allowing developers to build event-driven and API-based applications quickly using YAML schemas and minimal boilerplate. It supports both synchronous and asynchronous event sources like HTTP, Kafka, and Cron, and integrates with external systems via plugins.

How to install godspeed ?​

How to create a microservice ?​

Godspeed provides a CLI-based workflow to scaffold a new backend service in minutes. Follow these steps to spin up a project using the Godspeed CLI.

Step 1: Verify Godspeed installation using godspeed -V command. If not found, then first install godspeed using installation guide.

Step 2: Create a New Project using godspeed create <project-name>

This generates a standard Godspeed folder structure with all required configs.

Step 3: Navigate to the project folder and open it in your preferred code editor.

cd <project-name>

If You Want to Connect to a Database (DataSource)

Godspeed supports various database plugins like Prisma, Mongoose, mailer, sendgrid etc.

Add a datasource plugin

To use postgres, sqlite, mysql, mongodb and all other prisma-supported databases

Install prisma plugin

godspeed plugin add @godspeedsystems/plugins-prisma-as-datastore

Write Prisma Schema under src/datasources/ folder.

Check How to Use guide of prisma.

For other datasources, Check the auto generated datasource configuration file to configure the datasource as per your requirements.

Then start writing apis.

If You Want to Listen to some other EventSource like kafka, fastify, websocket, mcp etc.

Add the eventsource plugin

godspeed plugin add @godspeedsystems/plugins-websocket-as-eventsource

Check the auto generated eventsource configuration file src/eventsources/<plugin-name>.yaml to configure it as per your requirements.

Then start writing events and workflows.

How does the Godspeed CLI help developers?​

The godspeed CLI is your main interface for working with Godspeed projects. It can scaffold new projects, add or update plugins, start development servers, clean builds, and even generate full CRUD APIs or GraphQL schemas from defined models. It ensures all code follows Godspeed's conventions. godspeed commands run only within a godspeed framework project.

What is the typical folder structure of a Godspeed project?​

A standard Godspeed project has the following structure:

src/
  datasources/      # YAML configs for datasources (type = plugin)
    types/          # TypeScript type definitions for datasources (import plugin classes)
  events/           # YAML configs for events (routes, triggers)
  eventsources/     # YAML configs for event sources (type = plugin)
    types/          # TypeScript type definitions for eventsources (import plugin classes)
  functions/        # TS or YAML business logic
    validations/    # Request/response validation handlers (TS/YAML)
  mappings/         # Static mappings
  index.ts          # Entry point (bootstraps Godspeed)
config/             # Environment and default config
docs/               # API docs (Swagger)

Each folder has a specific purpose—from defining external API integrations to business logic and routing events.

How do I check if a plugin is installed in my Godspeed project?​

You can verify installed plugins using the Godspeed CLI or by checking your project structure.

✅ Method 1: Use the CLI Run:

godspeed plugin update

This lists all installed datasource and eventsource plugins in your project.

✅ Method 2: Check Your src/ Folder Look under: src/datasources/types/ — for datasource plugins (e.g., axios.ts, prisma.ts) src/eventsources/types/ — for eventsource plugins (e.g., express.ts, kafka.ts)

Corresponding YAML config should exist under src/datasources/ or src/eventsources/

✅ Method 3: Check package.json Look for installed plugin packages:

"@godspeedsystems/plugins-prisma-as-datastore": "^x.y.z",
"@godspeedsystems/plugins-kafka-as-datasource-as-eventsource": "^x.y.z"

If the plugin exists only here in package.json, means, it has been installed via npm and not by godspeed plugin add command.

What are the core concepts behind Godspeed?​

The Godspeed architecture is built around declarative entities such as:

  • Datasources (external API or DB definitions)
  • Events (triggers like HTTP routes or Kafka messages)
  • Eventsources (sources like HTTP servers or cron jobs)
  • Functions (TS or YAML-based business logic)
  • Mappings and Validations (supportive logic and error handling)

How do plugins work in Godspeed?​

Plugins in Godspeed extend its capabilities as:

  • EventSources (e.g., Express, Kafka, Cron)
  • DataSources (e.g., Axios, Prisma)
  • Combined (Kafka as both EventSource and DataSource)

They are loaded dynamically via YAML configurations where you specify the type (e.g., type: axios). The framework uses abstract classes like GSDataSource to enforce a standard plugin interface.

What does the godspeed gen-crud-api command do?​

It asks to you select your prisma schema file and eventsource you are using, then it scans your Prisma schema and automatically generates:

  • API event definitions
  • Workflows for Create, Read, Update, Delete operations
  • That can be tested via Swagger UI immediately

This command eliminates boilerplate and accelerates backend setup.

What are the key internal modules of the Godspeed engine?​

Key internal modules include:

  • configLoader.ts: Merges app configs.
  • datasourceLoader.ts & eventsourceLoader.ts: Load and initialize plugins.
  • functionLoader.ts: Loads all TS or YAML business logic.
  • validation/: Validates incoming/outgoing data against schemas.
  • interfaces.ts: Defines GSContext, GSStatus, and other core types.

Framework Internals​

  • Entity Loaders: Each entity type (datasource, eventsource, function, mapping) has a dedicated loader that reads YAML/TS files, resolves plugin types, and instantiates the correct classes.
  • Plugin Integration: Uses dynamic imports to load plugin classes based on the type field in YAML.
  • Abstract Interfaces: All plugins must extend the appropriate abstract class (GSDataSource, GSEventSource, or GSDataSourceAsEventSource), which define required methods like initClient, execute, and subscribeToEvent.
  • Schema Validation: Built-in validation for events and tasks using JSON schema and AJV.
  • Logging & Observability: Integrated logging and OpenTelemetry support.

Where are Swagger docs generated?​

Swagger JSON specs are auto-generated and stored under src/docs/http-swagger.json. You can view the api documentation via built-in Swagger UI, which helps in testing all APIs.

How to create your own npm plugin for godspeed ?​

What are the key classes and extensibility points in the Godspeed framework?​

Godspeed is built around a set of core classes and interfaces that provide consistency, extensibility, and observability across workflows, plugins, and event handling. Key components include:

GSContext The execution context available in every function, workflow, and plugin. Contains inputs, outputs, config, datasources, functions, logger, and more. Enables full traceability, logging, and resource access during event execution.

GSCloudEvent Represents the incoming request or event in a standard format (CloudEvents spec). Contains data, actor, headers, and other metadata.

GSStatus Standard response object used to represent the outcome of any function or workflow. Contains success, code, message, data, etc.

Plugin Base Classes GSDataSource: Extend this for custom outbound plugins (e.g., HTTP, DBs). GSEventSource: Extend this for plugins that handle inbound events (e.g., HTTP, Cron). GSDataSourceAsEventSource: For dual-role plugins like Kafka. GSCachingDataSource: For caching-specific plugins (like Redis), with get, set, del.

Other Core Types GSActor: Represents the user or system initiating the event. GSLogEvent: Structured log record used by GSContext.log_events.

These classes provide all the extensibility hooks for building plugins, writing business logic, and handling events consistently in a scalable Godspeed application.

What is the lifecycle of a Godspeed application at startup?​

When a Godspeed application starts, it goes through a defined lifecycle to prepare all runtime components. Here's how it works:

Application starts — This is triggered from the src/index.ts file in your project.

Configuration is loaded — It reads and merges all environment-specific and default configs from the config/ directory.

Datasources are initialized — Godspeed loads all YAML datasource definitions and instantiates the corresponding plugin clients from src/datasources/.

Eventsources are initialized — Plugins like Express or Kafka are set up from src/eventsources/ to start listening for incoming events.

Event definitions are loaded — Event handlers (HTTP routes, Kafka topics, etc.) are mapped to their respective functions via src/events/.

Functions and workflows are loaded — All TypeScript and YAML-based logic from src/functions/ becomes available for invocation.

Mappings and validations are loaded — Static key-value maps and request/response validation logic are pulled from src/mappings/ and src/functions/validations/.

App is ready — The service is now ready to process events, serve API requests, and run workflows based on triggers.

How is authentication handled in Godspeed?​

Godspeed supports robust and flexible authentication mechanisms using JWT, OAuth2, and custom auth workflows. Here's how you can secure your services:

Authentication Methods JWT/OAuth2: Configure these directly in your eventsource (e.g., Express) or datasource YAML files.

Example Configuration

authn:
  jwt:
    secretOrKey: mysecret
    audience: mycompany
    issuer: mycompany
  oauth2:
    linkedin:
      client_id:
      client_secret:
    github:
      client_id:
      client_secret:

GSActor Support Godspeed provides a GSActor object in every GSCloudEvent, which captures the identity and attributes of the user or system triggering the event. This makes it easy to propagate user context across workflows.

Best Practices Always validate JWT tokens and propagate the actor through the GSContext. Use role-based checks in your workflow logic or via authz tasks. Keep your secrets and auth config in the environment-safe config/ directory.

How do events trigger workflows in Godspeed?​

In Godspeed, events are declarative triggers that activate functions or workflows. These events are typically configured in YAML files under src/events/, and are mapped to logic defined in src/functions/.

Event-to-Function/Workflow Flow An event occurs — For example, an HTTP request, Kafka message, or Cron schedule. Event is mapped to a function/workflow — The fn: field in the event YAML points to a corresponding handler. Function/Workflow executes — The handler processes the request using the provided GSContext.

Setting up the APIs of your service​

Writing your Workflows or Functions​

In Godspeed, the words Workflows and Functions mean one and the same thing, i.e. your business logic.

Accessing other APIs, databases and datastores from workflows​

In Godspeed, datasource can mean any place where you send or retrieve data from. It could mean: