About this documentation

This component (dialer-v2) is not a standalone Antora site. It is designed to be added as a content source to a larger Antora playbook that aggregates documentation from several Payability repositories.

Consuming this component

Add the repository as a content source and point start_path at docs:

content:
  sources:
    - url: https://github.com/<org>/dialer-v2.git
      branches: [main]
      start_path: docs

The component descriptor is docs/antora.yml. It declares:

name: dialer-v2, title: Dialer V2
version: ~ — the component is unversioned, so its URLs carry no version segment. If the aggregating playbook needs branch-based versions, change this to version: true (derive from the branch) or a literal such as version: '1.0'.
start_page: ROOT:index.adoc
An explicit nav list, one entry per module.

Module layout

One module per concern, so that cross-references read as xref:MODULE:PAGE.adoc[]:

Module Scope

Module	Scope
`ROOT`	Landing page, stack, repository map, glossary, these conventions
`architecture`	Structure, layering, tenancy, async runtime, cross-cutting concerns
`domain`	Business logic and rules, per capability
`data`	Prisma models, enums, relations, indexes
`api`	HTTP reference, grouped by resource
`events`	Inbound webhooks and their handler registries
`workflows`	Durable Inngest functions
`integrations`	Third-party systems and how they are wired
`security`	Authentication, authorization, secrets, webhook verification
`frontend`	Dashboard routes, data layer, UI conventions
`ops`	Environment, local setup, deployment, scheduled jobs, troubleshooting

ROOT

Landing page, stack, repository map, glossary, these conventions

architecture

Structure, layering, tenancy, async runtime, cross-cutting concerns

domain

Business logic and rules, per capability

data

Prisma models, enums, relations, indexes

api

HTTP reference, grouped by resource

events

Inbound webhooks and their handler registries

workflows

Durable Inngest functions

integrations

Third-party systems and how they are wired

security

Authentication, authorization, secrets, webhook verification

frontend

Dashboard routes, data layer, UI conventions

ops

Environment, local setup, deployment, scheduled jobs, troubleshooting

Writing conventions

One = level-0 title per page, plus a :description: attribute — the aggregating site uses it for search snippets and social previews.
Code paths are written in monospace relative to the repository root, e.g. lib/services/phone-number-calling-service.ts. Do not use absolute paths.
API endpoints are written as METHOD /api/path with {id} for path parameters.
Field names use the casing of the layer being described: Prisma models are camelCase, API request/response bodies are snake_case. Say which layer you mean.
Prefer tables for enumerations of fields, statuses and endpoints; prefer prose for rules and rationale.
Record why a rule exists when the reason is not obvious from the rule itself. That is the part the code cannot express.

Diagrams

Diagrams are written as Mermaid inside a literal block with a [mermaid] style:

[mermaid]
....
flowchart TD
  A --> B
....

Without a diagram extension this renders as readable Mermaid source. To render it as an image, add asciidoctor-kroki to the playbook:

asciidoc:
  extensions:
    - asciidoctor-kroki
  attributes:
    kroki-fetch-diagram: true

Relationship to the in-app docs site

The repository also serves a Fumadocs site at /docs, built from the .mdx files that sit directly under docs/. Those files are the origin of much of this component’s content. Antora ignores them (it only reads docs/modules//pages), so the two can coexist, but they are *two sources of truth. When the Fumadocs site is retired, delete the .mdx files, source.config.ts, lib/source.ts and app/docs/, and this component becomes the only one.

Keeping it current

Update this component in the same change that alters behaviour:

schema change → data module and the relevant domain page
new or changed endpoint → api module
new webhook event type → events module
new Inngest function or step → workflows module
new environment variable → Environment variables