Class: RiviereBuilder

Defined in: packages/riviere-builder/src/builder.ts:105

Programmatically construct Rivière architecture graphs.

RiviereBuilder provides a fluent API for creating graphs, adding components, linking them together, and exporting valid JSON conforming to the Rivière schema.

Example

typescript

import { RiviereBuilder } from '@living-architecture/riviere-builder'

const builder = RiviereBuilder.new({
  sources: [{ type: 'git', url: 'https://github.com/org/repo' }],
  domains: { orders: { description: 'Order management' } }
})

const api = builder.addApi({
  name: 'Create Order',
  domain: 'orders',
  module: 'checkout',
  apiType: 'REST',
  sourceLocation: { file: 'src/api/orders.ts', line: 10 }
})

const graph = builder.build()

Properties

graph

graph: BuilderGraph

Defined in: packages/riviere-builder/src/builder.ts:106

Methods

addApi()

addApi(input): APIComponent

Defined in: packages/riviere-builder/src/builder.ts:293

Adds an API component to the graph.

Parameters

input

APIInput

API component properties including type, method, and path

Returns

APIComponent

The created API component with generated ID

Throws

If the specified domain does not exist

Example

typescript

const api = builder.addApi({
  name: 'Create Order',
  domain: 'orders',
  module: 'checkout',
  apiType: 'REST',
  httpMethod: 'POST',
  path: '/api/orders',
  sourceLocation: { file: 'src/api/orders.ts', line: 25 }
})

addCustom()

addCustom(input): CustomComponent

Defined in: packages/riviere-builder/src/builder.ts:524

Adds a Custom component to the graph.

Custom components use types defined via defineCustomType(). Validates that the custom type exists and required properties are provided.

Parameters

input

CustomInput

Custom component properties including type name and metadata

Returns

CustomComponent

The created Custom component with generated ID

Throws

If the specified domain does not exist

Throws

If the custom type has not been defined

Throws

If required properties for the custom type are missing

Example

typescript

const queue = builder.addCustom({
  customTypeName: 'MessageQueue',
  name: 'Order Events Queue',
  domain: 'orders',
  module: 'messaging',
  sourceLocation: { file: 'src/queues/orders.ts', line: 5 },
  metadata: { queueName: 'order-events' }
})

addDomain()

addDomain(input): void

Defined in: packages/riviere-builder/src/builder.ts:226

Adds a new domain to the graph.

Parameters

input

DomainInput

Domain name and description

Returns

void

Throws

If domain with same name already exists

Example

typescript

builder.addDomain({
  name: 'payments',
  description: 'Payment processing'
})

addDomainOp()

addDomainOp(input): DomainOpComponent

Defined in: packages/riviere-builder/src/builder.ts:370

Adds a DomainOp component to the graph.

DomainOp represents domain operations that change entity state. Can be enriched later with state changes and business rules.

Parameters

input

DomainOpInput

DomainOp component properties including operation name

Returns

DomainOpComponent

The created DomainOp component with generated ID

Throws

If the specified domain does not exist

Example

typescript

const domainOp = builder.addDomainOp({
  name: 'Confirm Order',
  domain: 'orders',
  module: 'fulfillment',
  operationName: 'confirmOrder',
  entity: 'Order',
  sourceLocation: { file: 'src/domain/Order.ts', line: 45 }
})

addEvent()

addEvent(input): EventComponent

Defined in: packages/riviere-builder/src/builder.ts:411

Adds an Event component to the graph.

Parameters

input

EventInput

Event component properties including event name

Returns

EventComponent

The created Event component with generated ID

Throws

If the specified domain does not exist

Example

typescript

const event = builder.addEvent({
  name: 'Order Placed',
  domain: 'orders',
  module: 'checkout',
  eventName: 'OrderPlaced',
  sourceLocation: { file: 'src/events/OrderPlaced.ts', line: 5 }
})

addEventHandler()

addEventHandler(input): EventHandlerComponent

Defined in: packages/riviere-builder/src/builder.ts:448

Adds an EventHandler component to the graph.

Parameters

input

EventHandlerInput

EventHandler component properties including subscribed events

Returns

EventHandlerComponent

The created EventHandler component with generated ID

Throws

If the specified domain does not exist

Example

typescript

const handler = builder.addEventHandler({
  name: 'Send Confirmation Email',
  domain: 'notifications',
  module: 'email',
  subscribedEvents: ['OrderPlaced'],
  sourceLocation: { file: 'src/handlers/OrderConfirmation.ts', line: 10 }
})

addSource()

addSource(source): void

Defined in: packages/riviere-builder/src/builder.ts:208

Adds an additional source repository to the graph.

Parameters

source

SourceInfo

Source repository information

Returns

void

Example

typescript

builder.addSource({
  type: 'git',
  url: 'https://github.com/org/another-repo'
})

addUI()

addUI(input): UIComponent

Defined in: packages/riviere-builder/src/builder.ts:255

Adds a UI component to the graph.

Parameters

input

UIInput

UI component properties including route and source location

Returns

UIComponent

The created UI component with generated ID

Throws

If the specified domain does not exist

Example

typescript

const ui = builder.addUI({
  name: 'Order List',
  domain: 'orders',
  module: 'dashboard',
  route: '/orders',
  sourceLocation: { file: 'src/pages/OrderList.tsx', line: 15 }
})

addUseCase()

addUseCase(input): UseCaseComponent

Defined in: packages/riviere-builder/src/builder.ts:331

Adds a UseCase component to the graph.

Parameters

input

UseCaseInput

UseCase component properties

Returns

UseCaseComponent

The created UseCase component with generated ID

Throws

If the specified domain does not exist

Example

typescript

const useCase = builder.addUseCase({
  name: 'Place Order',
  domain: 'orders',
  module: 'checkout',
  sourceLocation: { file: 'src/usecases/PlaceOrder.ts', line: 10 }
})

build()

build(): RiviereGraph

Defined in: packages/riviere-builder/src/builder.ts:832

Validates and returns the completed graph.

Returns

RiviereGraph

Valid RiviereGraph object

Throws

If validation fails with error details

Example

typescript

try {
  const graph = builder.build()
  console.log('Graph built successfully')
} catch (error) {
  console.error('Build failed:', error.message)
}

defineCustomType()

defineCustomType(input): void

Defined in: packages/riviere-builder/src/builder.ts:486

Defines a custom component type for the graph.

Custom types allow extending the schema with domain-specific component kinds. Must be defined before adding custom components of that type.

Parameters

input

CustomTypeInput

Custom type definition with required and optional properties

Returns

void

Throws

If a custom type with the same name already exists

Example

typescript

builder.defineCustomType({
  name: 'MessageQueue',
  description: 'Async message queue',
  requiredProperties: {
    queueName: { type: 'string', description: 'Queue identifier' }
  }
})

enrichComponent()

enrichComponent(id, enrichment): void

Defined in: packages/riviere-builder/src/builder.ts:564

Enriches a DomainOp component with additional domain details.

Adds state changes and business rules to an existing DomainOp. Multiple enrichments accumulate rather than replace.

Parameters

id

string

The component ID to enrich

enrichment

EnrichmentInput

State changes and business rules to add

Returns

void

Throws

If the component does not exist

Throws

If the component is not a DomainOp type

Example

typescript

builder.enrichComponent('orders:fulfillment:domainop:confirm-order', {
  entity: 'Order',
  stateChanges: [{ entity: 'Order', from: 'pending', to: 'confirmed' }],
  businessRules: ['Order must have valid payment']
})

link()

link(input): Link

Defined in: packages/riviere-builder/src/builder.ts:654

Creates a link between two components in the graph.

Source component must exist; target validation is deferred to build(). Use linkExternal() for connections to external systems.

Parameters

input

LinkInput

Link properties including source, target, and type

Returns

Link

The created link

Throws

If the source component does not exist

Example

typescript

const link = builder.link({
  from: 'orders:checkout:api:create-order',
  to: 'orders:checkout:usecase:place-order',
  type: 'sync'
})

linkExternal()

linkExternal(input): ExternalLink

Defined in: packages/riviere-builder/src/builder.ts:688

Creates a link from a component to an external system.

Use this for connections to systems outside the graph, such as third-party APIs or external databases.

Parameters

input

ExternalLinkInput

External link properties including target system info

Returns

ExternalLink

The created external link

Throws

If the source component does not exist

Example

typescript

const link = builder.linkExternal({
  from: 'orders:payments:usecase:process-payment',
  target: { name: 'Stripe API', domain: 'payments' },
  type: 'sync'
})

nearMatches()

nearMatches(query, options?): NearMatchResult[]

Defined in: packages/riviere-builder/src/builder.ts:631

Finds components similar to a query for error recovery.

Returns fuzzy matches when an exact component lookup fails, enabling actionable error messages with "Did you mean...?" suggestions.

Parameters

query

NearMatchQuery

Search criteria including partial ID, name, type, or domain

options?

NearMatchOptions

Optional matching thresholds and limits

Returns

NearMatchResult[]

Array of similar components with similarity scores

Example

typescript

const matches = builder.nearMatches({ name: 'Place Ordr' })
// [{ component: {...}, score: 0.9, mismatches: [...] }]

orphans()

orphans(): string[]

Defined in: packages/riviere-builder/src/builder.ts:777

Returns IDs of components with no incoming or outgoing links.

Returns

string[]

Array of orphaned component IDs

Example

typescript

const orphans = builder.orphans()
if (orphans.length > 0) {
  console.warn('Orphaned components:', orphans)
}

query()

query(): RiviereQuery

Defined in: packages/riviere-builder/src/builder.ts:794

Returns a RiviereQuery instance for the current graph state.

Enables querying mid-construction without affecting builder state.

Returns

RiviereQuery

RiviereQuery instance for the current graph

Example

typescript

const query = builder.query()
const apis = query.componentsByType('API')

save()

save(path): Promise<void>

Defined in: packages/riviere-builder/src/builder.ts:854

Validates the graph and writes it to a file.

Parameters

path

string

Absolute or relative file path to write

Returns

Promise<void>

Throws

If validation fails

Throws

If the directory does not exist

Throws

If write fails

Example

typescript

await builder.save('./output/architecture.json')

serialize()

serialize(): string

Defined in: packages/riviere-builder/src/builder.ts:812

Serializes the current graph state as a JSON string.

Does not validate. Use for saving drafts mid-construction that can be resumed later with RiviereBuilder.resume().

Returns

string

JSON string representation of the graph

Example

typescript

const json = builder.serialize()
await fs.writeFile('draft.json', json)

stats()

stats(): BuilderStats

Defined in: packages/riviere-builder/src/builder.ts:738

Returns statistics about the current graph state.

Returns

BuilderStats

Counts of components by type, domains, and links

Example

typescript

const stats = builder.stats()
console.log(`Components: ${stats.componentCount}`)
console.log(`Links: ${stats.linkCount}`)

validate()

validate(): ValidationResult

Defined in: packages/riviere-builder/src/builder.ts:760

Runs full validation on the graph.

Checks for dangling references, orphans, and schema compliance. Called automatically by build().

Returns

ValidationResult

Validation result with valid flag and error details

Example

typescript

const result = builder.validate()
if (!result.valid) {
  for (const error of result.errors) {
    console.error(error.message)
  }
}

warnings()

warnings(): BuilderWarning[]

Defined in: packages/riviere-builder/src/builder.ts:722

Returns non-fatal issues found in the graph.

Warnings indicate potential problems that don't prevent building, such as orphaned components or unused domains.

Returns

BuilderWarning[]

Array of warning objects with type and message

Example

typescript

const warnings = builder.warnings()
for (const w of warnings) {
  console.log(`${w.type}: ${w.message}`)
}

new()

static new(options): RiviereBuilder

Defined in: packages/riviere-builder/src/builder.ts:169

Creates a new builder with initial configuration.

Parameters

options

BuilderOptions

Configuration including sources and domains

Returns

RiviereBuilder

A new RiviereBuilder instance

Throws

If sources array is empty

Throws

If domains object is empty

Example

typescript

const builder = RiviereBuilder.new({
  name: 'My System',
  sources: [{ type: 'git', url: 'https://github.com/org/repo' }],
  domains: {
    orders: { description: 'Order management' },
    users: { description: 'User accounts' }
  }
})

resume()

static resume(graph): RiviereBuilder

Defined in: packages/riviere-builder/src/builder.ts:130

Restores a builder from a previously serialized graph.

Use this to continue building a graph that was saved mid-construction, or to modify an existing graph.

Parameters

graph

RiviereGraph

A valid RiviereGraph object to resume from

Returns

RiviereBuilder

A new RiviereBuilder instance with the graph state restored

Throws

If the graph is missing required sources

Example

typescript

const json = await fs.readFile('draft.json', 'utf-8')
const graph = JSON.parse(json)
const builder = RiviereBuilder.resume(graph)
builder.addApi({ ... })

Class: RiviereBuilder ​

Example ​

Properties ​

graph ​

Methods ​

addApi() ​

Parameters ​

input ​

Returns ​

Throws ​

Example ​

addCustom() ​

Parameters ​

input ​

Returns ​

Throws ​

Throws ​

Throws ​

Example ​

addDomain() ​

Parameters ​

input ​

Returns ​

Throws ​

Example ​

addDomainOp() ​

Parameters ​

input ​

Returns ​

Throws ​

Example ​

addEvent() ​

Parameters ​

input ​

Returns ​

Throws ​

Example ​

addEventHandler() ​

Parameters ​

input ​

Returns ​

Throws ​

Example ​

addSource() ​

Parameters ​

source ​

Returns ​

Example ​

addUI() ​

Parameters ​

input ​

Returns ​

Throws ​

Example ​

addUseCase() ​

Parameters ​

input ​

Returns ​

Throws ​

Example ​

build() ​

Returns ​

Throws ​

Example ​

defineCustomType() ​

Parameters ​

input ​

Returns ​

Throws ​

Example ​

enrichComponent() ​

Parameters ​

id ​

enrichment ​

Returns ​

Throws ​

Throws ​

Example ​

link() ​

Parameters ​

Class: RiviereBuilder

Example

Properties

graph

Methods

addApi()

Parameters

input

Returns

Throws

Example

addCustom()

Parameters

input

Returns

Throws

Throws

Throws

Example

addDomain()

Parameters

input

Returns

Throws

Example

addDomainOp()

Parameters

input

Returns

Throws

Example

addEvent()

Parameters

input

Returns

Throws

Example

addEventHandler()

Parameters

input

Returns

Throws

Example

addSource()

Parameters

source

Returns

Example

addUI()

Parameters

input

Returns

Throws

Example

addUseCase()

Parameters

input

Returns

Throws

Example

build()

Returns

Throws

Example

defineCustomType()

Parameters

input

Returns

Throws

Example

enrichComponent()

Parameters

id

enrichment

Returns

Throws

Throws

Example

link()

Parameters