### Start Figram Live Sync

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/installation.md

Starts the Figram WebSocket server to synchronize diagram changes from a YAML file to a FigJam canvas. Requires the FigJam plugin to be running and connected.

```bash
npx figram diagram.yaml
```

```bash
npx figram serve diagram.yaml
```

--------------------------------

### Serve Figram with Custom Icons File

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/installation.md

Starts the Figram server and specifies an alternative path for the custom icons configuration file. This allows for centralized icon management outside the default `figram-icons.yaml`.

```bash
npx figram serve diagram.yaml --icons path/to/my-icons.yaml
```

--------------------------------

### Clone and Install Dependencies with Bun

Source: https://github.com/7nohe/figram/blob/main/CONTRIBUTING.md

Steps to clone the figram repository, navigate into the directory, and install project dependencies using Bun. This is the initial setup for development.

```bash
git clone https://github.com/7nohe/figram.git
cd figram
bun install
```

--------------------------------

### Serve Figram with Remote Access and Secret

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/installation.md

Starts the Figram server, allows remote connections, and enforces authentication using a secret key. Clients must provide the secret to establish a connection, enhancing security.

```bash
npx figram serve diagram.yaml --allow-remote --secret my-secret
```

--------------------------------

### Start Figram Server and Watch Diagram File

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/quick-start.md

Starts the Figram WebSocket server, which watches the specified YAML file for changes. The server then pushes these changes to connected clients, such as the FigJam plugin, enabling live editing.

```bash
npx figram diagram.yaml
```

--------------------------------

### Start Figram Server with Custom Icons

Source: https://github.com/7nohe/figram/blob/main/examples/custom-icons/README.md

This command starts the figram development server, watches for changes in `diagram.yaml`, and automatically reloads. It's configured to use custom icons defined in the specified YAML file.

```bash
npx figram serve diagram.yaml --watch --icons ./path/to/icons.yaml
```

--------------------------------

### Serve Figram with Remote Access

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/installation.md

Starts the Figram server and allows connections from remote machines, in addition to localhost. This is necessary for team collaboration or accessing diagrams from different devices on a network.

```bash
npx figram serve diagram.yaml --allow-remote
```

--------------------------------

### Multi-AZ Production Setup (YAML)

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/examples.md

This YAML configuration defines a high-availability production environment spanning multiple Availability Zones. It includes a VPC, private subnets in AZ-A and AZ-C, ECS services, RDS instances (primary and standby), ElastiCache clusters, and an Application Load Balancer. The `layout` attribute controls the visual positioning of nodes.

```yaml
version: 1
docId: "multi-az"
title: "Multi-AZ Production"

nodes:
  - id: vpc
    provider: aws
    kind: network.vpc
    label: "VPC 10.0.0.0/16"
    layout: { x: 0, y: 0, w: 900, h: 700 }

  # AZ-A
  - id: subnet_a
    provider: aws
    kind: network.subnet
    label: "Private Subnet AZ-A"
    parent: vpc
    layout: { x: 40, y: 60, w: 400, h: 580 }

  # AZ-C
  - id: subnet_c
    provider: aws
    kind: network.subnet
    label: "Private Subnet AZ-C"
    parent: vpc
    layout: { x: 460, y: 60, w: 400, h: 580 }

  # AZ-A Resources
  - id: ecs_a
    provider: aws
    kind: compute.container.ecs_service
    label: "ECS Service AZ-A"
    parent: subnet_a
    layout: { x: 180, y: 80 }

  - id: rds_primary
    provider: aws
    kind: database.rds
    label: "RDS Primary"
    parent: subnet_a
    layout: { x: 260, y: 280 }

  - id: elasticache_a
    provider: aws
    kind: database.elasticache
    label: "Redis AZ-A"
    parent: subnet_a
    layout: { x: 60, y: 220 }

  # AZ-C Resources
  - id: ecs_c
    provider: aws
    kind: compute.container.ecs_service
    label: "ECS Service AZ-C"
    parent: subnet_c
    layout: { x: 120, y: 80 }

  - id: rds_standby
    provider: aws
    kind: database.rds
    label: "RDS Standby"
    parent: subnet_c
    layout: { x: 120, y: 380 }

  - id: elasticache_c
    provider: aws
    kind: database.elasticache
    label: "Redis AZ-C"
    parent: subnet_c
    layout: { x: 220, y: 220 }

  # External
  - id: alb
    provider: aws
    kind: compute.lb.alb
    label: "Application Load Balancer"
    layout: { x: 350, y: -120 }

edges:
  - id: alb_to_ecs_a
    from: alb
    to: ecs_a
    color: "#3498DB"

  - id: alb_to_ecs_c
    from: alb
    to: ecs_c
    color: "#3498DB"

  - id: ecs_a_to_rds
    from: ecs_a
    to: rds_primary
    label: "Write"
    color: "#27AE60"

  - id: ecs_c_to_rds
    from: ecs_c
    to: rds_primary
    label: "Write"
    color: "#27AE60"

  - id: rds_replication
    from: rds_primary
    to: rds_standby
    label: "Replication"
    color: "#E74C3C"

  - id: ecs_a_to_cache
    from: ecs_a
    to: elasticache_a
    color: "#E67E22"

  - id: ecs_c_to_cache
    from: ecs_c
    to: elasticache_c
    color: "#E67E22"

```

--------------------------------

### Initialize New Figram Diagram

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/quick-start.md

Initializes a new Figram diagram project, creating a `diagram.yaml` file with a basic structure. This file defines the version, document ID, title, nodes, and edges of the architecture diagram.

```bash
npx figram init
```

--------------------------------

### Programmatic Server Start using Figram CLI

Source: https://context7.com/7nohe/figram/llms.txt

Demonstrates how to programmatically start the Figram WebSocket server using its CLI module, typically for testing purposes. It allows configuring server options such as port, host, file watching, remote access, secret keys, and icon files. The function returns a server instance that can be closed later for cleanup.

```typescript
// Programmatic usage in tests
import { serveCommand } from "@figram/cli";

const server = await serveCommand("diagram.yaml", {
  port: 3456,
  host: "127.0.0.1",
  watch: true,
  allowRemote: false,
  secret: undefined,
  iconsFile: undefined
});

console.log(`Server running on port ${server.port}`);

// Cleanup
await server.close();
```

--------------------------------

### CLI - Serve with Live Sync

Source: https://context7.com/7nohe/figram/llms.txt

Starts a WebSocket server that watches the diagram YAML file for changes and broadcasts updates to connected clients, enabling live synchronization.

```APIDOC
## CLI - Serve with Live Sync

### Description
Start WebSocket server with file watching for live diagram updates. Launches an HTTP server with WebSocket endpoint that watches the diagram YAML file for changes. When changes are detected, validates the YAML, computes incremental patches, and broadcasts updates to connected FigJam plugin instances. Supports custom icons, remote connections, and authentication.

### Method
`npx figram serve` or `npx figram`

### Endpoint
N/A (CLI command)

### Parameters
#### Path Parameters
- **diagram.yaml** (string) - Required - Path to the input YAML diagram file.

#### Query Parameters
- **--port** (number) - Optional - Specifies the port for the WebSocket server (default: 3456).
- **--allow-remote** - Optional - Allows remote connections to the server.
- **--icons** (string) - Optional - Path to a custom icons YAML file.
- **--secret** (string) - Optional - Sets a secret key for authentication.
- **--no-watch** - Optional - Disables file watching and live updates.

### Request Example
```bash
# Start server (default command)
npx figram diagram.yaml
# WebSocket server listening on ws://127.0.0.1:3456
# Loaded: diagram.yaml (docId: my-architecture)

# Explicit serve command with options
npx figram serve diagram.yaml --port 8080 --allow-remote

# Custom icons file
npx figram diagram.yaml --icons custom-icons.yaml

# Require authentication
npx figram diagram.yaml --secret mysecretkey

# Disable file watching
npx figram diagram.yaml --no-watch

# File change triggers automatic sync:
# File changed: diagram.yaml
# [rev 2] 3 changes
```

### Request Example (Programmatic)
```typescript
import { serveCommand } from "@figram/cli";

const server = await serveCommand("diagram.yaml", {
  port: 3456,
  host: "127.0.0.1",
  watch: true,
  allowRemote: false,
  secret: undefined,
  iconsFile: undefined
});

console.log(`Server running on port ${server.port}`);

// Cleanup
await server.close();
```

### Response
#### Success Response (200)
- A WebSocket server is started, listening for connections and file changes.

#### Response Example
```
WebSocket server listening on ws://127.0.0.1:3456
Loaded: diagram.yaml (docId: my-architecture)
```
```

--------------------------------

### Figjam Example Diagram YAML

Source: https://github.com/7nohe/figram/blob/main/README.md

An example YAML file demonstrating how to define an AWS production environment architecture for FigJam. It includes nodes for VPC, ALB, ECS, and RDS, along with their relationships.

```yaml
version: 1
docId: "my-architecture"
title: "Production Environment"

nodes:
  - id: vpc
    provider: aws
    kind: network.vpc
    label: "VPC 10.0.0.0/16"
    layout: { x: 0, y: 0, w: 800, h: 500 }

  - id: alb
    provider: aws
    kind: compute.lb.alb
    label: "ALB"
    parent: vpc
    layout: { x: 100, y: 100 }

  - id: ecs
    provider: aws
    kind: compute.container.ecs_service
    label: "ECS Service"
    parent: vpc
    layout: { x: 100, y: 250 }

  - id: rds
    provider: aws
    kind: database.rds
    label: "RDS PostgreSQL"
    parent: vpc
    layout: { x: 300, y: 250 }

edges:
  - id: alb_to_ecs
    from: alb
    to: ecs
    label: "HTTP:80"

  - id: ecs_to_rds
    from: ecs
    to: rds
    label: "TCP:5432"

```

--------------------------------

### Configure Custom Icons in Figram

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/installation.md

Defines custom icon mappings for cloud provider resources in a `figram-icons.yaml` file. This allows visual representation of specific services using local image files.

```yaml
version: 1
icons:
  aws:
    "compute.ec2": "./icons/ec2.png"
    "database.rds": "./icons/rds.png"
    "compute.lambda": "./icons/lambda.png"
```

--------------------------------

### Bash Commands for Figram Project Management

Source: https://github.com/7nohe/figram/blob/main/CLAUDE.md

A collection of essential bash commands for managing the Figram project, including installing dependencies, running tests (all, watch, single file, specific package), type checking, linting and formatting (check and fix), and building packages (all, plugin, CLI dev).

```bash
# Install dependencies
bun install

# Run all tests
bun test

# Run tests in watch mode
bun test --watch

# Run a single test file
bun test packages/core/src/diff.test.ts

# Run tests for specific package
bun test packages/core/

# Type check
bun run typecheck

# Lint and format check
bun run check

# Lint and format fix
bun run check:fix

# Build all packages
bun run build

# Build FigJam plugin
cd packages/plugin && bun run build

# Run CLI directly (dev)
bun run packages/cli/src/index.ts <command>
```

--------------------------------

### Install Figram CLI

Source: https://github.com/7nohe/figram/blob/main/packages/cli/README.md

Installs the Figram command-line interface globally using either npm or bun package managers. This makes the `figram` command available in your terminal.

```bash
npm install -g figram
```

```bash
bun add -g figram
```

--------------------------------

### Build Figram Diagram to JSON

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/installation.md

Converts a Figram YAML diagram file into a JSON format, producing a `diagram.json` output file.

```bash
npx figram build diagram.yaml
```

--------------------------------

### Install Figjam CLI

Source: https://github.com/7nohe/figram/blob/main/README.md

Installs the Figjam command-line interface globally using npm. This command is essential for using Figjam's features from your terminal.

```bash
npm install -g figram
```

--------------------------------

### Initialize Figjam Diagram Template

Source: https://github.com/7nohe/figram/blob/main/packages/cli/README.md

Creates a `diagram.yaml` template file in the current directory. This template provides a starting point for defining your architecture diagrams.

```bash
figram init
```

--------------------------------

### Run Tests with Bun

Source: https://github.com/7nohe/figram/blob/main/CONTRIBUTING.md

Commands to execute the test suite for verifying the development setup and ongoing code changes. Includes options for running all tests or specific packages.

```bash
# Run all tests
bun run test

# Run tests in watch mode
bun run test:watch

# Run tests for a specific package
cd packages/core && bun test
```

--------------------------------

### Serve Figjam Diagram with Options

Source: https://github.com/7nohe/figram/blob/main/README.md

Starts the Figjam WebSocket server with optional configurations. You can specify the port, host, disable file watching, allow remote connections, and set a secret for added security.

```bash
npx figram serve diagram.yaml
# or explicitly:
npx figram serve diagram.yaml

# With options:
npx figram serve diagram.yaml --port 8080 --host 0.0.0.0 --no-watch --allow-remote --secret mysecret
```

--------------------------------

### Initialize Diagram Template with Figram CLI

Source: https://context7.com/7nohe/figram/llms.txt

Generates a starter YAML file with example AWS architecture including VPC, subnets, and resources. Fails if diagram.yaml already exists to prevent accidental overwrites. This command is executed in the terminal.

```bash
# Create new diagram in current directory
npx figram init

# Output:
# Created diagram.yaml

```

--------------------------------

### Descriptive IDs Example (YAML)

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/examples.md

This YAML snippet demonstrates the recommended practice of using descriptive IDs for nodes in Figram diagrams. Clear and meaningful IDs, such as `vpc_production` or `subnet_private_a`, enhance the understandability of the diagram, whereas generic IDs like `n1` or `n2` can lead to confusion. This practice is crucial for maintaining clarity in large or complex diagrams.

```yaml
# Good
- id: vpc_production
- id: subnet_private_a
- id: rds_primary

# Avoid
- id: n1
- id: n2

```

--------------------------------

### Start Figjam Server with Custom Icons

Source: https://github.com/7nohe/figram/blob/main/README.md

Launches the Figjam server while also loading a custom icons configuration file. This allows your diagrams to use user-defined icons specified in a separate YAML file.

```bash
npx figram serve diagram.yaml --icons figram-icons.yaml
```

--------------------------------

### Unit Test Structure in TypeScript

Source: https://github.com/7nohe/figram/blob/main/CONTRIBUTING.md

An example of how to structure unit tests using the `bun:test` module. It demonstrates the use of `describe`, `expect`, and `it` for defining test cases.

```typescript
import { describe, expect, it } from "bun:test";

describe("functionName", () => {
  it("should do something specific", () => {
    const result = functionName(input);
    expect(result).toBe(expected);
  });

  it("should handle edge case", () => {
    // ...
  });
});
```

--------------------------------

### Define Microservices Architecture with Auto-Layout in YAML

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/examples.md

This YAML demonstrates microservices architecture with AWS components and utilizes auto-layout features for simplified positioning of child nodes within a parent container like a subnet.

```yaml
version: 1
docId: "microservices"
title: "Microservices Architecture"

nodes:
  - id: vpc
    provider: aws
    kind: network.vpc
    label: "VPC"
    layout: { x: 0, y: 0, w: 900, h: 600 }

  - id: subnet
    provider: aws
    kind: network.subnet
    label: "Private Subnet"
    parent: vpc
    layout: { w: 820, h: 520 }  # x/y auto-positioned

  # These nodes are auto-positioned in a 3-column grid
  - id: user_service
    provider: aws
    kind: compute.container.ecs_service
    label: "User Service"
    parent: subnet

  - id: order_service
    provider: aws
    kind: compute.container.ecs_service
    label: "Order Service"
    parent: subnet
    layout: { x: 400, y: 200 }

  - id: payment_service
    provider: aws
    kind: compute.container.ecs_service
    label: "Payment Service"
    parent: subnet

  - id: notification_service
    provider: aws
    kind: compute.container.ecs_service
    label: "Notification Service"
    parent: subnet
    layout: { x: 600, y: 300 }

  - id: user_db
    provider: aws
    kind: database.rds
    label: "User DB"
    parent: subnet
    layout: { x: 100, y: 200 }

  - id: order_db
    provider: aws
    kind: database.rds
    label: "Order DB"
    parent: subnet
    layout: { x: 100, y: 400 }

edges:
  - id: user_to_db
    from: user_service
    to: user_db

  - id: order_to_db
    from: order_service
    to: order_db

  - id: order_to_payment
    from: order_service
    to: payment_service
    label: "Process Payment"

  - id: order_to_notification
    from: order_service
    to: notification_service
    label: "Send Notification"

```

--------------------------------

### Run Figjam CLI with npx

Source: https://github.com/7nohe/figram/blob/main/README.md

Executes Figjam commands directly without a global installation using npx. This is a convenient way to run Figjam commands, especially if you don't want to install it globally.

```bash
npx figram <command>
```

--------------------------------

### Auto-Layout for Child Nodes (YAML)

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/examples.md

This YAML example illustrates how to leverage Figram's auto-layout feature for child nodes. By omitting the `layout` attribute for nodes that have a `parent` defined, Figram automatically positions them within their parent's boundaries, typically in a grid format. This simplifies diagram creation by reducing the need for manual positioning of every element.

```yaml
- id: service_1
  parent: subnet
  # No layout = auto-positioned

- id: service_2
  parent: subnet
  # No layout = next position in grid

```

--------------------------------

### YAML Example: AWS VPC Container Node

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/yaml-specs.md

Shows the YAML configuration for an AWS Virtual Private Cloud (VPC) acting as a container. This example highlights the inclusion of width (`w`) and height (`h`) properties within the layout, which are typical for container elements.

```yaml
- id: vpc
  provider: aws
  kind: network.vpc
  label: "VPC 10.0.0.0/16"
  layout: { x: 0, y: 0, w: 800, h: 600 }
```

--------------------------------

### Serve Figjam Diagram with File Watching

Source: https://github.com/7nohe/figram/blob/main/packages/cli/README.md

Starts a WebSocket server that serves the specified YAML diagram file and watches for changes. When the file is updated, the server will automatically reload the diagram in FigJam.

```bash
figram serve diagram.yaml
```

--------------------------------

### Figram Edge Properties and Examples (YAML)

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/yaml-specs.md

Defines the structure for representing connections (edges) between nodes in a Figram diagram. Includes properties like id, from, to, label, and color, with examples of their usage in YAML format.

```yaml
edges:
  - id: alb_to_ecs
    from: alb
    to: ecs
    label: "HTTP:80"
    color: "#FF5733"  # Orange

  - id: ecs_to_rds
    from: ecs
    to: rds
    label: "PostgreSQL:5432"
    color: "#3498DB"  # Blue
```

--------------------------------

### Define Serverless API Architecture in YAML

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/examples.md

This YAML defines a serverless API architecture using AWS Lambda, API Gateway, DynamoDB, S3, and SQS. It showcases how to connect different serverless components and storage.

```yaml
version: 1
docId: "serverless-api"
title: "Serverless API"

nodes:
  - id: apigw
    provider: aws
    kind: network.apigateway
    label: "API Gateway"
    layout: { x: 0, y: 100 }

  - id: lambda_api
    provider: aws
    kind: compute.lambda
    label: "API Handler"
    layout: { x: 400, y: 100 }

  - id: dynamodb
    provider: aws
    kind: database.dynamodb
    label: "DynamoDB"
    layout: { x: 600, y: 100 }

  - id: s3
    provider: aws
    kind: storage.s3
    label: "S3 Bucket"
    layout: { x: 600, y: 450 }

  - id: sqs
    provider: aws
    kind: integration.sqs
    label: "SQS Queue"
    layout: { x: 600, y: 250 }

  - id: lambda_worker
    provider: aws
    kind: compute.lambda
    label: "Worker Lambda"
    layout: { x: 0, y: 250 }

edges:
  - id: apigw_to_lambda
    from: apigw
    to: lambda_api
    label: "REST"

  - id: lambda_to_dynamo
    from: lambda_api
    to: dynamodb
    label: "Query"

  - id: lambda_to_sqs
    from: lambda_api
    to: sqs
    label: "Publish"

  - id: sqs_to_worker
    from: sqs
    to: lambda_worker
    label: "Trigger"

  - id: worker_to_s3
    from: lambda_worker
    to: s3
    label: "Upload"

```

--------------------------------

### YAML Node Definition with Auto-Layout Example

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/yaml-specs.md

Illustrates how to define nested nodes within a parent container in YAML, demonstrating the auto-layout feature. It shows a VPC container with child nodes (subnet, EC2 instances, RDS) that omit explicit layout coordinates, allowing the system to position them automatically. An example of explicit positioning for a Lambda function is also included.

```yaml
nodes:
  # Container: requires explicit layout with w/h
  - id: vpc
    provider: aws
    kind: network.vpc
    label: "VPC"
    layout: { x: 0, y: 0, w: 800, h: 600 }

  # Container child: needs w/h, can auto-position x/y
  - id: subnet
    provider: aws
    kind: network.subnet
    label: "Private Subnet"
    parent: vpc
    layout: { w: 700, h: 500 }  # x/y auto: (40, 40)

  # Leaf nodes: can omit layout entirely
  - id: ec2_1
    provider: aws
    kind: compute.ec2
    label: "Web Server 1"
    parent: subnet
    # No layout - auto: (40, 40)

  - id: ec2_2
    provider: aws
    kind: compute.ec2
    label: "Web Server 2"
    parent: subnet
    # No layout - auto: (200, 40)

  - id: rds
    provider: aws
    kind: database.rds
    label: "Database"
    parent: subnet
    # No layout - auto: (360, 40)

  # Explicit positioning overrides auto-layout
  - id: lambda
    provider: aws
    kind: compute.lambda
    label: "Lambda"
    parent: subnet
    layout: { x: 500, y: 300 }  # Custom position
```

--------------------------------

### Define Basic Web Application Architecture in YAML

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/examples.md

This YAML defines a 3-tier web application architecture using AWS components like VPC, Subnets, ALB, ECS, and RDS. It illustrates node and edge definitions for creating a visual diagram.

```yaml
version: 1
docId: "web-app"
title: "Basic Web Application"

nodes:
  - id: vpc
    provider: aws
    kind: network.vpc
    label: "VPC 10.0.0.0/16"
    layout: { x: 0, y: 0, w: 800, h: 500 }

  - id: subnet_public
    provider: aws
    kind: network.subnet
    label: "Public Subnet"
    parent: vpc
    layout: { x: 40, y: 60, w: 360, h: 380 }

  - id: subnet_private
    provider: aws
    kind: network.subnet
    label: "Private Subnet"
    parent: vpc
    layout: { x: 420, y: 60, w: 360, h: 380 }

  - id: alb
    provider: aws
    kind: compute.lb.alb
    label: "ALB"
    parent: subnet_public
    layout: { x: 100, y: 120 }

  - id: ecs
    provider: aws
    kind: compute.container.ecs_service
    label: "ECS Service"
    parent: subnet_private
    layout: { x: 100, y: 120 }

  - id: rds
    provider: aws
    kind: database.rds
    label: "RDS PostgreSQL"
    parent: subnet_private
    layout: { x: 100, y: 260 }

edges:
  - id: alb_to_ecs
    from: alb
    to: ecs
    label: "HTTP:80"

  - id: ecs_to_rds
    from: ecs
    to: rds
    label: "PostgreSQL:5432"

```

--------------------------------

### External Figram Icons Configuration

Source: https://github.com/7nohe/figram/blob/main/examples/custom-icons/README.md

This YAML file, named `figram-icons.yaml` and placed in the same directory as the diagram, allows for auto-discovery of custom icons. It defines mappings from icon identifiers to their file paths, similar to inline definitions.

```yaml
# figram-icons.yaml
version: 1
icons:
  aws:
    "compute.ec2": "./icons/server.svg"
```

--------------------------------

### Organizing Nodes by Layer (YAML)

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/examples.md

This YAML snippet showcases a recommended organizational structure for nodes within a Figram diagram. It suggests grouping nodes by their respective layers in the infrastructure stack, such as Network, Compute, and Data layers. This logical arrangement improves the clarity and readability of the diagram, making it easier to understand the overall architecture.

```yaml
nodes:
  # Network layer
  - id: vpc
  - id: subnet_public
  - id: subnet_private

  # Compute layer
  - id: alb
  - id: ecs

  # Data layer
  - id: rds
  - id: elasticache

```

--------------------------------

### YAML Example: Simple AWS Resource Node

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/yaml-specs.md

Demonstrates the YAML definition for a single AWS Application Load Balancer (ALB) node. It specifies the node's ID, provider, kind, a human-readable label, and its layout coordinates.

```yaml
- id: alb
  provider: aws
  kind: compute.lb.alb
  label: "Application Load Balancer"
  layout: { x: 100, y: 100 }
```

--------------------------------

### Inline Icon Definition in Figram Diagram

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/installation.md

Embeds custom icon definitions directly within the `diagram.yaml` file. This provides a way to override or define specific icons for individual nodes.

```yaml
version: 1
docId: "prod"
icons:
  aws:
    "compute.ec2": "./icons/ec2.png"
    "database.rds": "./icons/rds.png"
nodes:
  - id: web
    provider: aws
    kind: compute.ec2
    # ...
```

--------------------------------

### Add RDS Node to Figram Diagram

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/quick-start.md

An example snippet demonstrating how to add a new node, specifically an AWS RDS PostgreSQL instance, to an existing Figram diagram definition in YAML. This illustrates the live editing capability.

```yaml
  - id: rds
    provider: aws
    kind: database.rds
    label: "PostgreSQL"
    parent: subnet_public
    layout: { x: 100, y: 260 }
```

--------------------------------

### Figram Diagram YAML Structure

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/quick-start.md

Defines the structure of a Figram architecture diagram using YAML. It includes metadata like version and docId, and specifications for nodes (e.g., AWS VPC, Subnet, ALB) and edges connecting them.

```yaml
version: 1
docId: "my-architecture"
title: "My Architecture Diagram"

nodes:
  - id: vpc
    provider: aws
    kind: network.vpc
    label: "VPC 10.0.0.0/16"
    layout: { x: 0, y: 0, w: 800, h: 500 }

  - id: subnet_public
    provider: aws
    kind: network.subnet
    label: "Public Subnet"
    parent: vpc
    layout: { x: 40, y: 60, w: 360, h: 380 }

  - id: alb
    provider: aws
    kind: compute.lb.alb
    label: "ALB"
    parent: subnet_public
    layout: { x: 100, y: 120 }

edges:
  - id: alb_to_ecs
    from: alb
    to: ecs
    label: "HTTP:80"
```

--------------------------------

### Plugin - Apply Full Sync

Source: https://context7.com/7nohe/figram/llms.txt

Explains how the plugin renders a complete diagram from the received IR document, creating/updating nodes, frames, and connectors.

```APIDOC
## Plugin - Apply Full Sync

Render complete diagram from IR document

Creates or updates all nodes and edges in FigJam based on the received IR document. Nodes are created as shapes with provider icons, containers become frames, and edges become connectors. Existing elements are updated in place to preserve manual position adjustments.

### Request Example (Plugin code.ts)
```typescript
import { applyFull, type IRDocument } from "@figram/plugin";

// Received from CLI via WebSocket
const message = {
  type: "full",
  rev: 1,
  ir: {
    docId: "production",
    nodes: {
      "vpc": {
        id: "vpc",
        kind: "network.vpc",
        label: "VPC",
        layout: { x: 0, y: 0, w: 800, h: 500 }
      },
      "ec2": {
        id: "ec2",
        kind: "compute.ec2",
        label: "Web Server",
        parent: "vpc",
        layout: { x: 100, y: 100, w: null, h: null }
      }
    },
    edges: {
      "e1": {
        id: "e1",
        from: "ec2",
        to: "rds",
        label: "DB:5432",
        color: "#27AE60"
      }
    }
  }
};

// Apply to FigJam canvas
await applyFull(message.ir);

// Result:
// - SECTION node created: "figram: production"
// - FRAME created for VPC at (0, 0) with size 800x500
// - SHAPE created for EC2 at (100, 100) inside VPC frame
// - CONNECTOR created from EC2 to RDS with label "DB:5432" and green color
// - All nodes tagged with plugin data for future updates
```
```

--------------------------------

### Serve Figram Diagrams with Live Sync

Source: https://context7.com/7nohe/figram/llms.txt

Launches an HTTP server with a WebSocket endpoint that watches a specified YAML diagram file for changes. Upon detecting modifications, it validates the YAML, computes incremental patches, and broadcasts updates to connected FigJam plugin instances. This facilitates real-time diagram updates. It supports various options like custom ports, remote connections, authentication, custom icons, and disabling file watching.

```bash
# Start server (default command)
npx figram diagram.yaml
# WebSocket server listening on ws://127.0.0.1:3456
# Loaded: diagram.yaml (docId: my-architecture)

# Explicit serve command with options
npx figram serve diagram.yaml --port 8080 --allow-remote

# Custom icons file
npx figram diagram.yaml --icons custom-icons.yaml

# Require authentication
npx figram diagram.yaml --secret mysecretkey

# Disable file watching
npx figram diagram.yaml --no-watch

# File change triggers automatic sync:
# File changed: diagram.yaml
# [rev 2] 3 changes
```

--------------------------------

### Build Packages with Bun

Source: https://github.com/7nohe/figram/blob/main/CONTRIBUTING.md

Commands to build all packages within the figram workspace or to build a specific package. This is essential for generating distributable code.

```bash
# Build all packages
bun run build

# Build specific package
cd packages/plugin && bun run build
```

--------------------------------

### Figjam Plugin Constraints: Main Thread (code.ts)

Source: https://github.com/7nohe/figram/blob/main/CLAUDE.md

Illustrates the limitations of the main thread ('code.ts') within the FigJam plugin, emphasizing the absence of browser APIs and the necessity of using only the 'figma.*' API for communication.

```typescript
// NO browser APIs: window, document, fetch, WebSocket are unavailable
// Use only figma.* API
// Communication with UI only via figma.ui.postMessage()
```

--------------------------------

### WebSocket Protocol - Connection Flow

Source: https://context7.com/7nohe/figram/llms.txt

Details the initial connection handshake between the CLI and plugins, including message types like 'hello', 'welcome', 'full', and 'icons'.

```APIDOC
## WebSocket Protocol - Connection Flow

Establish authenticated connection between CLI and plugin

The plugin initiates connection with a hello message containing docId and optional secret. The CLI responds with a welcome message including version information, then sends a full sync with the complete IR document and custom icons if available.

### Request Example (Plugin → CLI: Initiate connection)
```json
{
  "type": "hello",
  "docId": "my-architecture",
  "secret": "mysecretkey",
  "pluginVersion": "1.2.0"
}
```

### Response Example (CLI → Plugin: Acknowledge connection)
```json
{
  "type": "welcome",
  "cliVersion": "1.2.0",
  "protocolVersion": 1
}
```

### Response Example (CLI → Plugin: Full sync with initial state)
```json
{
  "type": "full",
  "rev": 1,
  "ir": {
    "version": 1,
    "docId": "my-architecture",
    "title": "Production",
    "nodes": { /* ... */ },
    "edges": { /* ... */ }
  }
}
```

### Response Example (CLI → Plugin: Custom icons (if configured))
```json
{
  "type": "icons",
  "icons": {
    "custom": {
      "myservice": "data:image/png;base64,iVBORw0KG..."
    }
  }
}
```
```

--------------------------------

### Figjam Plugin Constraints: UI Thread (ui.ts)

Source: https://github.com/7nohe/figram/blob/main/CLAUDE.md

Details the constraints for the UI iframe ('ui.ts') in the FigJam plugin, highlighting the availability of browser APIs and the requirement to serialize data for the main thread via postMessage.

```typescript
// Browser APIs available
// Must serialize all data to main thread via postMessage
```

--------------------------------

### Plugin: Apply Full Sync to FigJam (TypeScript)

Source: https://context7.com/7nohe/figram/llms.txt

Demonstrates how the Figram plugin applies a full synchronization message received from the CLI to render the complete diagram in FigJam. It handles nodes, edges, and preserves manual layout adjustments.

```typescript
// Plugin code.ts (main thread)
import { applyFull, type IRDocument } from "@figram/plugin";

// Received from CLI via WebSocket
const message = {
  type: "full",
  rev: 1,
  ir: {
    docId: "production",
    nodes: {
      "vpc": {
        id: "vpc",
        kind: "network.vpc",
        label: "VPC",
        layout: { x: 0, y: 0, w: 800, h: 500 }
      },
      "ec2": {
        id: "ec2",
        kind: "compute.ec2",
        label: "Web Server",
        parent: "vpc",
        layout: { x: 100, y: 100, w: null, h: null }
      }
    },
    edges: {
      "e1": {
        id: "e1",
        from: "ec2",
        to: "rds",
        label: "DB:5432",
        color: "#27AE60"
      }
    }
  }
};

// Apply to FigJam canvas
await applyFull(message.ir);

// Result:
// - SECTION node created: "figram: production"
// - FRAME created for VPC at (0, 0) with size 800x500
// - SHAPE created for EC2 at (100, 100) inside VPC frame
// - CONNECTOR created from EC2 to RDS with label "DB:5432" and green color
// - All nodes tagged with plugin data for future updates

```

--------------------------------

### Figram Edge Color Customization (YAML)

Source: https://github.com/7nohe/figram/blob/main/packages/docs/src/content/docs/en/yaml-specs.md

Demonstrates how to customize the color of edges in Figram diagrams using HEX color codes. Supports full HEX, shorthand HEX, and case-insensitivity, with an example showing the default gray color.

```yaml
edges:
  # Full HEX format
  - id: e1
    from: a
    to: b
    color: "#FF5733"

  # Shorthand format
  - id: e2
    from: b
    to: c
    color: "#F53"

  # Lowercase
  - id: e3
    from: c
    to: d
    color: "#3498db"

  # No color (uses default gray)
  - id: e4
    from: d
    to: e
```

--------------------------------

### CLI - Load and Parse Diagrams (Programmatic)

Source: https://context7.com/7nohe/figram/llms.txt

Provides programmatic access to utilities for loading, parsing, and validating diagram YAML files, enabling custom integrations and workflows.

```APIDOC
## CLI - Load and Parse Diagrams

### Description
Pipeline utilities for reading and validating YAML files. Provides a composable set of functions for the YAML to IR transformation pipeline, with both throwing and non-throwing variants for different error handling strategies.

### Method
Import from `@figram/cli/lib/diagram`

### Endpoint
N/A (Programmatic module)

### Parameters
N/A (Functions take arguments as per their definitions)

### Request Example (Throwing variant)
```typescript
import {
  loadIRFromYamlFile
} from "@figram/cli/lib/diagram";

try {
  const { ir } = await loadIRFromYamlFile("diagram.yaml");
  console.log(`Loaded: ${ir.docId}`);
} catch (error) {
  console.error(`Failed: ${error.message}`);
  process.exit(1);
}
```

### Request Example (Non-throwing variant)
```typescript
import {
  tryLoadDiagram
} from "@figram/cli/lib/diagram";

const result = await tryLoadDiagram("diagram.yaml");
if (result.error) {
  console.error(`Parse error: ${result.error}`);
  // Send error to connected clients, don't crash server
} else {
  console.log(`Loaded successfully: ${result.ir.docId}`);
  // Compute and broadcast patch
}
```

### Request Example (Manual pipeline control)
```typescript
import {
  ensureFileExists,
  readDiagramFile,
  parseDiagramYaml,
  validateDiagram,
  toIR
} from "@figram/cli/lib/diagram";

ensureFileExists("diagram.yaml");
const content = await readDiagramFile("diagram.yaml");
const parsed = parseDiagramYaml(content); // May throw YamlParseError
const dsl = validateDiagram(parsed);      // May throw ValidationError
const ir = toIR(dsl);
```

### Response
#### Success Response (200)
- Functions return parsed data, IR objects, or status indicators based on their purpose.

#### Response Example
```json
// Example IR object returned by successful load/parse operations
{
  "version": 1,
  "docId": "my-architecture",
  "title": "My Architecture Diagram",
  // ... rest of the IR structure
}
```
```