# Workflow Schema Documentation

This document describes the structure and purpose of the workflow YAML format used in Bangstack.

## Overview

A workflow file describes a complete feature or capability from multiple perspectives:
- **Frontend**: User interface and interactions
- **Backend**: API endpoints and business logic
- **Database**: Data models and relationships
- **Documentation**: User and developer docs
- **Testing**: Test scenarios and coverage
- **Deployment**: Environment and configuration

## Top-Level Structure

### `workflow` (required)

Metadata about the workflow:

```yaml
workflow:
  id: unique-identifier
  version: 1.0.0
  name: Human Readable Name
  description: What this workflow accomplishes
  domains: [domain-tags]
  actors: [who interacts with this workflow]
  relationships: [connections to other workflows]
```

**Key concepts:**
- `id`: Unique identifier for referencing this workflow
- `actors`: Who uses/builds/maintains this workflow (customer, frontend-dev, backend-dev, etc.)
- `relationships`: How changes to this workflow affect others
  - `prerequisite`: Must exist before this workflow
  - `dependent`: Relies on this workflow
  - `related`: Connected but not strictly dependent

### `frontend` (optional)

Describes UI components and interactions:

```yaml
frontend:
  framework: react # swappable implementation
  components:
    - id: component-id
      type: form-component | list-component | detail-component
      ui: # visual specifications
      state: # component state management
      actions: # user interactions and API calls
      generate: # code generation hints
```

**Key concepts:**
- Components are self-contained UI units
- `actions` define what happens on user interaction
- `steps` within actions create a dependency graph
- API calls reference backend endpoints via `api_workflow`

### `backend` (optional)

Describes API endpoints and business logic:

```yaml
backend:
  language: typescript # swappable implementation
  framework: express # swappable implementation
  endpoints:
    - id: endpoint-id
      path: /api/resource
      method: POST | GET | PUT | DELETE
      request: # request schema
      responses: # response schemas by status code
      implementation: # processing steps
      middleware: # security, rate limiting, etc.
```

**Key concepts:**
- Endpoints are self-contained API handlers
- `implementation.steps` define the processing pipeline
- Steps have dependencies via `depends_on`
- Each step can specify error handling via `onError`, `onNotFound`, etc.
- `action` types include:
  - `validate-schema`: Input validation
  - `database-query`: Database operations
  - `crypto-compare`: Password verification
  - `generate-jwt`: Token generation
  - `respond`: Send response to client

### `database` (optional)

Describes required data models:

```yaml
database:
  tables:
    - name: table_name
      description: Purpose of this table
      required_fields:
        - name: field_name
          type: uuid | string | timestamp | integer | boolean
          constraints: primary_key | unique | indexed | foreign_key
```

### `documentation` (optional)

Describes generated documentation:

```yaml
documentation:
  user_docs:
    - title: Documentation Title
      sections:
        - heading: Section Heading
          content: Markdown content
          steps: [ordered instructions]

  developer_docs:
    - title: API Documentation
      sections:
        - heading: Endpoint Description
          examples:
            - language: curl | javascript | python
              code: Example code snippet
```

### `testing` (optional)

Describes test coverage:

```yaml
testing:
  unit_tests:
    - component: frontend.component-id | backend.endpoint-id
      scenarios: [test case descriptions]

  integration_tests:
    - name: test-name
      steps: [test steps]

  e2e_tests:
    - name: test-name
      tool: playwright | cypress
      steps: [browser automation steps]
```

### `environment` (optional)

Environment-specific configuration:

```yaml
environment:
  development:
    backend:
      VAR_NAME: value

  production:
    backend:
      VAR_NAME: "{{ secrets.SECRET_NAME }}"
```

### `deployment` (optional)

Deployment specifications:

```yaml
deployment:
  frontend:
    build_command: npm run build
    output_directory: dist

  backend:
    build_command: npm run build
    start_command: npm start
    health_check:
      path: /health
```

## Swappable Implementations

One of the core features is the ability to swap implementations:

**Framework swapping:**
```yaml
frontend:
  framework: react  # Change to: vue, angular, svelte, solid
```

**Language swapping:**
```yaml
backend:
  language: typescript  # Change to: go, python, rust, java
  framework: express    # Change to: fastify, nest, koa
```

**Service swapping:**
```yaml
- id: verify-password
  action: crypto-compare
  implementation: bcrypt  # Change to: argon2, scrypt
```

The workflow engine will use the appropriate code generator based on these selections.

## Workflow Relationships

Workflows can reference each other to create a dependency graph:

```yaml
workflow:
  relationships:
    - workflow: user-registration
      type: prerequisite
      reason: Users must register before they can authenticate
```

When a workflow changes, the engine can:
1. Identify affected workflows
2. Regenerate dependent code
3. Update related documentation
4. Alert stakeholders

## Step Dependencies and Execution Order

Both frontend actions and backend implementations use a step-based system:

```yaml
steps:
  - id: step-1
    action: some-action

  - id: step-2
    action: another-action
    depends_on: [step-1]  # Runs after step-1

  - id: step-3
    action: final-action
    depends_on: [step-1, step-2]  # Runs after both complete
```

The engine will:
1. Build a directed acyclic graph (DAG) of steps
2. Execute steps in topological order
3. Handle errors according to `onError` specifications
4. Pass data between steps via template variables

## Template Variables

Use `{{ }}` syntax to reference data:

```yaml
payload:
  email: "{{ state.email }}"          # From component state
  userId: "{{ find-user.result.id }}" # From previous step
  timestamp: "{{ now }}"               # Built-in function
  secret: "{{ env.JWT_SECRET }}"      # Environment variable
```

## Next Steps

This schema is designed to be:
1. **Declarative**: Describe what, not how
2. **Swappable**: Change implementations without changing logic
3. **Connected**: Workflows reference each other
4. **Generative**: Produce code, docs, and tests from single source

The Bangstack engine will parse these workflows and generate:
- Complete application code in the specified tech stack
- Comprehensive documentation for all stakeholders
- Test suites with coverage
- Deployment configurations
- Change impact reports
