Skip to main content

Architecture Overview

Wrkbelt is a multi-tenant platform that helps service businesses convert leads into bookings. This section is the architectural reference: how the shipped system is built, where it's heading, and the decisions behind both.

What Wrkbelt is​

  • An NX integrated monorepo
  • A NestJS API horizontally scaled across multiple ECS tasks
  • A Next.js 15 application (App Router) deployed on AWS via SST + OpenNext
  • An embeddable React scheduler widget injected into customer marketing sites
  • A multi-tenant data plane (MongoDB + Redis) backing all of it

The platform is currently at v0.6.0 — the walking-skeleton and multi-instance work has shipped, and the architecture has stabilized around the patterns documented here.

Who Wrkbelt serves​

Wrkbelt's tenant model is a four-level hierarchy. Every authenticated request resolves to a tenant in this hierarchy, and every authorization check runs against both the actor's identity and the targeted tenant.

  • Platform — Wrkbelt's own org. Houses superadmin users; allowed to act on anything via identity-based authority.
  • Portfolio — a holding company or aggregator that owns multiple Brands. Inherits permissions downward.
  • Partner — a franchise or agency org that operates on behalf of Brands.
  • Brand — a single service business. The unit of customer-facing booking flows, ServiceTitan connection, and product enablement.

A Brand can have a Portfolio parent, a Partner parent, or both; Platform sits above all of them. The hierarchy is materialized as an ancestry_path on each organization document.

How to read this section​

The architecture section is split into three parts. Pick based on what you're trying to do:

If you want to…Start here
Understand how the platform works todayCurrent State
See where the architecture is goingFuture State
Understand why the shipped system is shaped this wayDecisions

Current State — what's shipped​

These pages describe the v0.6.0 architecture. Every claim cites a code anchor — you can jump from the doc straight to the code that backs it. The seven major subsystems, in reading order:

  • Multi-tenant hierarchy — org types, ancestry, dual-check authorization, the @TargetOrgId decorator, impersonation, session org context, ancestry cache
  • Catalog and enablement — ProductDefinition and IntegrationDefinition catalog; OrgProduct, IntegrationInstance, VendorCredential entities; the strategy pattern
  • Multi-instance runtime — production topology, the four ioredis clients, semantic Redis services, Socket.IO fanout, cron + SQS
  • Cluster coordination pattern — the decision guide for picking the right coordination primitive
  • Booking session pipeline — unified gateway → SQS dedup pipeline, deriveEventId, processor idempotency
  • Data model and migrations — entity layout under types-data, base entity + discriminators, MigrationBootCoordinator, idempotency log
  • Audit and observability — two-tier audit writes, CloudWatch alarms, structured-log keys, Sentry integration

Future State — where it's going​

These pages describe target architecture that is not yet shipped. Each page opens with a status banner and names its tracking ticket plus OpenSpec proposal.

Decisions — why it's this way​

OpenSpec specs at openspec/specs/ are the durable contract record. The decisions section captures the rationale for architectural choices — both for shipped patterns and for decisions deliberately deferred with a known revisit trigger.

What the platform handles​

Five subsystems, owned by the architecture section in this order:

  1. Tenancy + authorization — org hierarchy, dual-check authorization, session context, impersonation.
  2. Catalog + enablement — defining which Products are available, mapping them to required Integrations per industry, and tracking per-org activation state.
  3. Booking flow runtime — the embeddable scheduler widget and its server-side state machine. The booking session pipeline handles real-time events; the booking flow builder is the operator-facing canvas.
  4. Multi-instance runtime — horizontal scaling primitives (Redis, SQS, Socket.IO adapter) so the API can run as an autoscaled cluster without coordination bugs.
  5. Audit + observability — SOC 2-grade audit trail (two-tier write strategy), structured-log keys feeding CloudWatch alarms, Sentry distributed tracing.

For everything else — UI component patterns, scheduler product behavior, QA strategy — see the UI, Products, and Quality sections.

Working with this section​

If you're touching architecture-level code, the workflow is:

  1. Read the current-state page for the subsystem you're working in.
  2. Check openspec/specs/ for the contract record (linked from each current-state page).
  3. If your change crosses subsystems, read the Cluster coordination pattern — picking the wrong coordination primitive is the most common silent bug.
  4. If you're proposing a change to a deferred decision, check Decisions → Deferred for the existing revisit trigger before opening a new RFC.

The architecture section deliberately does not duplicate OpenSpec or the API reference. It links into them.