System design

Modular by responsibility. Simple to deploy.

The prototype begins as a TypeScript modular monolith with separate Nuxt, API, and worker entrypoints. Clean ports isolate every unstable external dependency.

3runtime entrypoints

1system of record

5external ports

0required message brokers

Overview

Runtime and dependency map

High-level architecture — The core workflow depends on stable internal ports. Provider SDKs, selectors, cookies, and request shapes never leak into domain modules.

Principles

The rules that keep it modular

Domain stays pure

Preferences, rules, product intent, money, time, and state transitions import no NestJS, Playwright, ORM, or model SDK.

Adapters absorb change

OpenAI, Anthropic, Chrome, Browserbase, Stop & Shop pages, notifications, and secret storage implement internal contracts.

Workflow owns side effects

Only Order Orchestration coordinates cart changes. Scheduling triggers work; Intelligence only proposes; Rules decide deterministically.

Runtime topology

Three entrypoints, one codebase

Runtime	Owns	May call	Must not do
Nuxt web	SSR, dashboard, settings, review, live status	Application API	Direct database, provider, or retailer access
Node API	Authentication, commands, queries, SSE, consent	Application services and Postgres	Start browser sessions or run long jobs inline
Node worker	Durable tasks, browser sessions, retailer operations	Module services, adapters, Postgres	Accept public user traffic

Core stack

Recommended implementation baseline

Frontend

Nuxt 4 · Vue 3 · TypeScript

Backend

NestJS · Fastify · Zod

Data

PostgreSQL · Drizzle

Jobs

Graphile Worker · transactional outbox

Browser

Playwright · CDP · optional Browserbase

Observability

Structured logs · traces · metrics · audit

PostgreSQL is more than storage

It is the consistency boundary for schedule deduplication, workflow state, approval snapshots, job outbox, and audit history. A separate Redis or broker is unnecessary for the prototype.

Data path

One correlated chain from schedule to evidence

trace_id
  → schedule_occurrence_id
  → order_cycle_id
  → job_id
  → browser_session_id
  → retailer_operation_id
  → intelligence_run_id
  → audit_event_id