> ## Documentation Index
> Fetch the complete documentation index at: https://doc.codika.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Cases

> The fundamental deployment unit — a folder containing config, workflows, and metadata that defines a complete automation

## 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](/concepts/agent-skills).         |
| `deployments/` | Local archive of past deployments. Created automatically by `codika deploy`.                                                                                                                                 |

## config.ts structure

The config file must export these members:

```typescript theme={null}
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:

```json theme={null}
{
  "version": "1.2.3"
}
```

On each deploy, the CLI:

1. Reads the current version
2. Bumps it based on the flag: `--patch` (default), `--minor`, or `--major`
3. Sends the API version to the platform (X.Y format)
4. 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](/concepts/processes) for full details on the deployment lifecycle.