AGENTS.md - Macrograph Project Guide

Project Overview

Macrograph is a visual programming platform with node-based graph interfaces. Supports both desktop (single-project) and server (multi-project) environments with real-time event processing and type-safe ID management.

Documentation Structure

This guide provides essential information for working with Macrograph. For detailed technical documentation, see the

agents/

folder.

Quick Start

Read the Critical Rules below (especially #1 about branded types)
Check agents/project-runtime.md for architecture details
Review agents/effect-ts.md for Effect patterns

Need Help?

Branded types: See rule #1 below
Architecture questions: agents/project-runtime.md
Effect patterns: agents/effect-ts.md

Technology Stack

Effect-TS: Functional programming framework with Effect system, Layer dependency injection, Stream processing, and Schema validation
Branded Types: Type-safe IDs using
```
Schema.brand()
```
(ProjectId, GraphId, NodeId, PackageId, SchemaId)
Core Libraries: HashMap (immutable collections), Ref (mutable state), Queue/Stream (event processing)

Critical Rules for AI Agents

1. Branded Type Usage - MANDATORY

NEVER use

as

type assertions. Always use
.make()
methods:

// ✅ CORRECT
const projectId = ProjectId.make(123);
const packageId = PackageId.make("core");

// ❌ INCORRECT - Never do this
const projectId = 123 as ProjectId;

2. Effect Patterns

Always work within Effect context:

const program = Effect.gen(function* () {
  const projectService = yield* ProjectService;
  return yield* projectService.get();
});

3. Error Handling

Use Effect's error channels, not try-catch:

yield* pipe(
  operation(),
  Effect.catchTag("ProjectNotFoundError", () => Effect.succeed(defaultProject))
);

4. State Management

Use immutable patterns:

yield* Ref.set(runtime.projectRef, Option.some(project));

Architecture

Core Services

ProjectService: Single project operations
GraphService: Graph and node management
ProjectRegistry: Multi-project coordination
PackageRegistry: Schema package management
IOManager: Node IO calculation and caching
EventStream: Event publishing and subscription

Key Models

Project: Top-level container with graphs and auto-incrementing IDs
Graph: Container for nodes within a project
Node: Programming units with schema references and properties
SchemaRef: References to package schema definitions

Runtime Isolation

Each project runs in isolated

ProjectRuntime

with independent state, event queues, and event node caches.

TypeScript Tooling

THIS IS VERY IMPORTANT

Do NOT use TypeScript CLI (

tsc

) or
typecheck
command for type checking. Use LSP diagnostics instead:

VS Code or LSP-compatible editors show proper type errors
Biome handles linting and formatting
TypeScript CLI fails due to complex Effect-TS types
Never run
npm run typecheck
or
tsc
commands

Common Patterns

Create Project

const project = yield* registry.create("My Project");

Add Node

const node = yield* graphService.addNode(
  graphId,
  new SchemaRef({
    pkgId: PackageId.make("core"),
    schemaId: SchemaId.make("log")
  }),
  "Logger Node"
);

Multi-Project Context

yield* withProjectRuntime(
  ProjectId.make(projectId),
  Effect.gen(function* () {
    const graphService = yield* GraphService;
    // Operations within project context
  })
);

Key Principles

Type Safety First: Branded IDs prevent runtime errors
Effect Everything: All operations in Effect context
Immutable State: No direct mutations, use Ref/HashMap
Layered Architecture: Proper dependency injection
Event-Driven: React to state changes via events
Error Propagation: Typed errors with Schema.TaggedError

Quick Reference

ProjectId.make(number): Create project ID
GraphId.make(number): Create graph ID
NodeId.make(number): Create node ID
PackageId.make(string): Create package ID
SchemaId.make(string): Create schema ID

Never use:

as ProjectId

as GraphId

as NodeId

as PackageId

as SchemaId

Checking your code

Formatting: Run
```
pnpm format
```
Linting: Don't bother
Type Checking: Use the TypeScript LSP if available, otherwise don't bother

AGENTS.md - Macrograph Project Guide

Project Overview

Documentation Structure

This guide provides essential information for working with Macrograph. For detailed technical documentation, see the

agents/

folder.

Quick Start

Read the Critical Rules below (especially #1 about branded types)
Check agents/project-runtime.md for architecture details
Review agents/effect-ts.md for Effect patterns

Need Help?

Branded types: See rule #1 below
Architecture questions: agents/project-runtime.md
Effect patterns: agents/effect-ts.md

Technology Stack

Effect-TS: Functional programming framework with Effect system, Layer dependency injection, Stream processing, and Schema validation
Branded Types: Type-safe IDs using
```
Schema.brand()
```
(ProjectId, GraphId, NodeId, PackageId, SchemaId)
Core Libraries: HashMap (immutable collections), Ref (mutable state), Queue/Stream (event processing)

Critical Rules for AI Agents

1. Branded Type Usage - MANDATORY

NEVER use

as

type assertions. Always use
.make()
methods:

// ✅ CORRECT
const projectId = ProjectId.make(123);
const packageId = PackageId.make("core");

// ❌ INCORRECT - Never do this
const projectId = 123 as ProjectId;

2. Effect Patterns

Always work within Effect context:

const program = Effect.gen(function* () {
  const projectService = yield* ProjectService;
  return yield* projectService.get();
});

3. Error Handling

Use Effect's error channels, not try-catch:

yield* pipe(
  operation(),
  Effect.catchTag("ProjectNotFoundError", () => Effect.succeed(defaultProject))
);

4. State Management

Use immutable patterns:

yield* Ref.set(runtime.projectRef, Option.some(project));

Architecture

Core Services

ProjectService: Single project operations
GraphService: Graph and node management
ProjectRegistry: Multi-project coordination
PackageRegistry: Schema package management
IOManager: Node IO calculation and caching
EventStream: Event publishing and subscription

Key Models

Project: Top-level container with graphs and auto-incrementing IDs
Graph: Container for nodes within a project
Node: Programming units with schema references and properties
SchemaRef: References to package schema definitions

Runtime Isolation

Each project runs in isolated

ProjectRuntime

with independent state, event queues, and event node caches.

TypeScript Tooling

THIS IS VERY IMPORTANT

Do NOT use TypeScript CLI (

tsc

) or
typecheck
command for type checking. Use LSP diagnostics instead:

VS Code or LSP-compatible editors show proper type errors
Biome handles linting and formatting
TypeScript CLI fails due to complex Effect-TS types
Never run
npm run typecheck
or
tsc
commands

Common Patterns

Create Project

const project = yield* registry.create("My Project");

Add Node

const node = yield* graphService.addNode(
  graphId,
  new SchemaRef({
    pkgId: PackageId.make("core"),
    schemaId: SchemaId.make("log")
  }),
  "Logger Node"
);

Multi-Project Context

yield* withProjectRuntime(
  ProjectId.make(projectId),
  Effect.gen(function* () {
    const graphService = yield* GraphService;
    // Operations within project context
  })
);

Key Principles

Type Safety First: Branded IDs prevent runtime errors
Effect Everything: All operations in Effect context
Immutable State: No direct mutations, use Ref/HashMap
Layered Architecture: Proper dependency injection
Event-Driven: React to state changes via events
Error Propagation: Typed errors with Schema.TaggedError

Quick Reference

ProjectId.make(number): Create project ID
GraphId.make(number): Create graph ID
NodeId.make(number): Create node ID
PackageId.make(string): Create package ID
SchemaId.make(string): Create schema ID

Never use:

as ProjectId

as GraphId

as NodeId

as PackageId

as SchemaId

Checking your code

Formatting: Run
```
pnpm format
```
Linting: Don't bother
Type Checking: Use the TypeScript LSP if available, otherwise don't bother

AGENTS.md - Macrograph Project Guide

Related Skills

Nano Banana Pro

Markdown Converter

1password