# 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

## 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](https://docs.synode.dev/getting-started): Install and first journey in 5 minutes
- [Guides](https://docs.synode.dev/guides/personas): Deep dives on each feature
- [API Reference](https://docs.synode.dev/api/types): Every export documented
- [Cookbook](https://docs.synode.dev/cookbook): Real-world recipes

## 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).