# Synode

> Synthetic data engine for Customer Data Platforms. Generate realistic, stateful user journeys with proper event sequences, timing, and cross-dataset relationships.

Synode is a TypeScript library (ESM + CJS) organized as a pnpm monorepo under the `@synode` npm scope.

## Packages

- @synode/core: Core engine — types, generators, execution, validation, telemetry, built-in adapters
- @synode/cli: CLI tool — `synode generate|validate|init`
- @synode/adapter-file: File output adapter (JSONL, JSON, CSV with daily partitioning)
- @synode/adapter-http: HTTP webhook adapter with batching and retry
- @synode/adapter-stream: Node.js writable stream adapter
- @synode/adapter-composite: Fan-out adapter writing to multiple adapters
- @synode/adapter-bigquery: BigQuery adapter for importing datasets and exporting events
- synode-vscode: VS Code extension with IntelliSense, validation, and navigation for Synode configs

## Core Concepts

Synode organizes generation around three pillars — Users, Datasets, and Journeys — composed in a four-level hierarchy:

```
Journey → Adventure → Action → Event[]
```

- Journey: High-level user goal (e.g., "Purchase Flow"), can have `requires` prerequisites
- Adventure: Session/interaction period with `timeSpan` and `bounceChance`
- Action: Specific behavior returning Event[] via a `handler` or `fields`
- Event: Atomic tracking point `{ id, userId, sessionId, name, timestamp, payload }`

## Documentation

- [Getting Started](/getting-started): Install and first journey in 5 minutes
- [Guides](/guides/personas): Deep dives on each feature
  - [Personas](/guides/personas): Weighted attribute distributions
  - [Datasets](/guides/datasets): Typed datasets with InferDatasetRow
  - [Multi-Journey](/guides/multi-journey): Prerequisites and shared context
  - [Parallel Processing](/guides/parallel-processing): Lanes and worker threads
  - [Real-Time Streaming](/guides/streaming): Concurrent sessions, pacing, continuous mode
  - [Output Adapters](/guides/output-adapters): All 7 built-in adapters
  - [Event Validation](/guides/event-validation): Zod schema validation
  - [CLI](/guides/cli): Config-driven generation
  - [Custom Adapters](/guides/custom-adapters): Build your own OutputAdapter
  - [BigQuery](/guides/bigquery): Import datasets and export events via BigQuery
- [API Reference](/api/types): Every export documented
  - [Types](/api/types)
  - [Builders](/api/builders)
  - [Execution](/api/execution)
  - [Adapters](/api/adapters)
  - [Validation](/api/validation)
  - [Telemetry](/api/telemetry)
- [Cookbook](/cookbook): Real-world recipes
- [Migration](/migration): Upgrading from pre-1.0

## Quick Start

```typescript
import { defineAction, defineAdventure, defineJourney, generate, InMemoryAdapter } from '@synode/core';

const pageView = defineAction({
  id: 'page-view',
  name: 'page_viewed',
  fields: { url: '/home', title: 'Home Page' },
});

const browsing = defineAdventure({
  id: 'browse',
  name: 'Browse',
  actions: [pageView],
});

const visit = defineJourney({
  id: 'visit',
  name: 'Website Visit',
  adventures: [browsing],
});

const adapter = new InMemoryAdapter();
await generate(visit, { users: 50, adapter });
console.log(`Generated ${adapter.events.length} events`);
```

## Optional: Full docs as markdown

For the complete documentation in a single file, see [/llms-full.txt](/llms-full.txt).