Use Cases

What is a use case?

A use case is Codika’s deployment unit. It is a folder on disk that contains everything needed to deploy one or more n8n workflows as a single automation to the Codika platform. When deployed, a use case becomes a Process that users can discover, install, and run with their own credentials.

Folder structure

my-use-case/
  config.ts                    # Required: deployment configuration
  version.json                 # Required: semantic version (auto-managed)
  project.json                 # Optional: platform project ID and org ID
  workflows/
    main-workflow.json         # Required: at least one workflow
    helper-workflow.json       # Optional: sub-workflows
  skills/                      # Optional: agent skills for triggerable workflows
    main-workflow/
      SKILL.md                 # Claude-compatible skill file
    scheduled-report/
      SKILL.md
  deployments/                 # Auto-created: deployment archives
    {projectId}/
      project-info.json
      process/
        {apiVersion}/
          deployment-info.json
          config-snapshot.json
          workflows/*.json

Required files

File	Purpose
`config.ts`	Exports `WORKFLOW_FILES`, `getConfiguration()`, and optionally `getDeploymentInputSchema()` and `getDefaultDeploymentParameters()`
`version.json`	Tracks the local semantic version (e.g., `{"version": "1.2.3"}`). Updated automatically on deploy.
`workflows/*.json`	n8n workflow JSON files. Each file listed in `WORKFLOW_FILES` is packaged and sent to the platform.

Optional files

File	Purpose
`project.json`	Contains `projectId`, `organizationId`, `devProcessInstanceId`, `prodProcessInstanceId`, and `deployments` map. Created by `codika init` or `codika project create --path .`. Updated on deploy and publish.
`skills/`	Agent skill directories. Each subdirectory contains a `SKILL.md` file describing how to interact with a workflow. Automatically collected during deploy. See Agent Skills.
`deployments/`	Local archive of past deployments. Created automatically by `codika deploy`.

config.ts structure

The config file must export these members:

import { loadAndEncodeWorkflow } from 'codika';
import { fileURLToPath } from 'url';
import { dirname } from 'path';
import crypto from 'crypto';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// Required: array of workflow file paths (relative to config.ts)
export const WORKFLOW_FILES = [
  'workflows/main-workflow.json',
  'workflows/helper-workflow.json',
];

// Required: returns the full deployment configuration
export function getConfiguration(): ProcessDeploymentConfigurationInput {
  return {
    title: 'My Automation',
    subtitle: 'One-line description of what it does',
    description: 'Longer description of capabilities and benefits.',
    workflows: [
      {
        workflowTemplateId: 'main-workflow',
        workflowId: 'main-workflow',
        workflowName: 'Main Workflow',
        integrationUids: ['anthropic', 'google_gmail'],
        triggers: [/* trigger definitions */],
        outputSchema: [/* output field definitions */],
        n8nWorkflowJsonBase64: loadAndEncodeWorkflow(
          __dirname, 'workflows/main-workflow.json'
        ),
        cost: 10,
      },
    ],
    tags: ['email', 'ai'],
  };
}

Configuration fields

Field	Type	Required	Description
`title`	string	Yes	Display name (2-5 words)
`subtitle`	string	No	One-line tagline
`description`	string	Yes	1-2 sentences describing the automation
`workflows`	array	Yes	Array of workflow configurations
`tags`	string[]	No	Categorization tags
`processDeploymentMarkdown`	string	No	Markdown documentation for the process

Workflow configuration fields

Field	Type	Required	Description
`workflowTemplateId`	string	Yes	Unique identifier for the workflow
`workflowId`	string	Yes	Must match the `workflowId` parameter in Codika Init node
`workflowName`	string	Yes	Display name
`integrationUids`	string[]	Yes	Required integrations (e.g., `['google_gmail', 'anthropic']`)
`triggers`	array	Yes	At least one trigger definition
`outputSchema`	array	Yes	Output field definitions (empty array `[]` for sub-workflows)
`n8nWorkflowJsonBase64`	string	Yes	Base64-encoded workflow JSON
`cost`	number	No	Execution cost in credits (0 for sub-workflows)
`markdownInfo`	string	No	Workflow-specific documentation

Version management

The version.json file tracks a semantic version:

{
  "version": "1.2.3"
}

On each deploy, the CLI:

Reads the current version
Bumps it based on the flag: --patch (default), --minor, or --major
Sends the API version to the platform (X.Y format)
Writes the new version back to version.json

Local bump	Example	API version strategy
`--patch` (default)	1.0.0 → 1.0.1	`minor_bump`
`--minor`	1.0.1 → 1.1.0	`minor_bump`
`--major`	1.1.0 → 2.0.0	`major_bump`
`--target-version 3.0`	Any → explicit	`explicit` (version 3.0)

Relationship to platform entities

When you deploy a use case, the platform creates linked records:

Use case folder
  → Process (public listing, discoverable)
    → Deployment template (immutable version snapshot)

  → Process instance (user installation with settings and activation state)
    → Deployment instance (running copy with live n8n workflow IDs)

See Processes for full details on the deployment lifecycle.

Getting Started

Why Codika

Core Concepts

Guides

Builder System

Examples

What is a use case?

Folder structure

Required files

Optional files

config.ts structure

Configuration fields

Workflow configuration fields

Version management

Relationship to platform entities

​What is a use case?

​Folder structure

​Required files

​Optional files

​config.ts structure

​Configuration fields

​Workflow configuration fields

​Version management

​Relationship to platform entities

What is a use case?

Folder structure

Required files

Optional files

config.ts structure

Configuration fields

Workflow configuration fields

Version management

Relationship to platform entities