INFRASTRUCTURE BLUEPRINT TRADE PARTNER · MULTI-TRADE · VESTRA HANDSHAKE

What we are NOT building

• A new database, a new auth provider, or a new vendor. Everything composes on Cloudflare + Drizzle + D1.
• Native iOS / Android apps. PWA SvelteKit gets us to install-on-home-screen + offline queue at a fraction of the cost. Revisit at 100+ trade partners.
• A standalone "supplier exchange" product. Suppliers are adapters behind one schema, not a marketplace UI.
• Anything that duplicates Procore. Procore stays the source of truth for the head contract / SC / commitment. We push to it, we don't replace it.

Three SvelteKit apps on top of one Workers API and one D1. Shared bindings, shared session KV, single event stream via Durable Objects.

Migration strategy · existing D1s

Today there are two D1 dbs: hillbrook-handoffs-db (postcon) and hillbrook-tenant-management-fresh (Vestra). Step 1 of S1 is to merge them into a single hop-core D1 with the canonical schema below, using Drizzle migrations. Both existing apps switch their bindings during the same release. We don't keep them as separate dbs — that's where drift starts.

Three GitHub repos, one shared package registry. Monorepo via pnpm workspaces — keeps Drizzle schema as one source of truth without forcing us to merge three SvelteKit apps into one.

Proposed layout

hop-platform/             # new umbrella repo
├── apps/
│   ├── postcon/             # import-as-submodule or move
│   │   ├── src/
│   │   ├── wrangler.toml      # DB=hop-core, BUCKET=hop-evidence
│   │   └── package.json
│   ├── vestra/              # import-as-submodule or move
│   │   ├── src/
│   │   └── package.json
│   └── trade-partner/       # NEW · sprint 2
│       ├── src/
│       │   ├── routes/
│       │   │   ├── (auth)/login/
│       │   │   ├── (app)/home/
│       │   │   ├── (app)/jobs/
│       │   │   ├── (app)/clients/
│       │   │   ├── (app)/build/      # materials + labour
│       │   │   ├── (app)/claim/
│       │   │   └── (app)/me/
│       │   └── lib/
│       ├── wrangler.toml
│       └── package.json
├── packages/
│   ├── db/                  # Drizzle schema · single source
│   │   ├── schema/
│   │   │   ├── site.ts
│   │   │   ├── defect.ts
│   │   │   ├── booking.ts
│   │   │   ├── trade_partner.ts
│   │   │   ├── vendor_inventory.ts
│   │   │   ├── labour_rate.ts
│   │   │   ├── work_order.ts
│   │   │   ├── product.ts
│   │   │   ├── supplier.ts
│   │   │   └── price_quote.ts
│   │   ├── migrations/
│   │   └── index.ts
│   ├── auth/                # JWT + scope claim parsing
│   ├── adapters/            # supplier adapter contracts + impls
│   │   ├── core/SupplierAdapter.ts
│   │   ├── middys/            # electrical
│   │   ├── voltex/
│   │   ├── reece/             # plumbing
│   │   ├── tradelink/
│   │   └── bunnings/          # cross-trade
│   ├── events/              # DO + SSE channels
│   ├── quote-engine/        # margin · cheapest-source · WO assembly
│   └── ui/                  # tokens + Adecion + components
├── workers/
│   ├── api/                 # shared Workers API for all 3 apps
│   ├── queue-consumer/      # supplier sync · procore push
│   └── job-do/              # Durable Object per active job
├── pnpm-workspace.yaml
├── package.json
└── README.md

Repo decision

Owner-friendly path: keep hillbrook-postcon and hillbrook-tenant as their own repos, create hop-platform as the umbrella with the shared packages + new trade-partner app. Use pnpm overrides / git submodules to consume the shared packages from postcon and Vestra during cut-over, then either fully absorb or stay loose-coupled. Derek's call.

Ownership

• @hop/db · Derek (schema authority — every change is a Drizzle migration PR)
• @hop/adapters · one engineer per supplier · template pattern below
• @hop/events · Derek (DO is the hard part)
• @hop/quote-engine · pure-function package, easy to write tests against
• apps/trade-partner · one engineer can own end-to-end, leans on the packages

Drizzle, SQLite dialect, single hop-core D1. Money in *Cents integers (existing Vestra convention). Timestamps as Unix epoch seconds. Soft-delete via deletedAt only on user-visible rows. UUIDv7 for ids.

Core tables (consolidated · existing + new)

Site & portfolio (existing in postcon)

Trade partner (NEW)

Trade partner ↔ client (NEW)

Vendor inventory (NEW · own stock · van / garage / yard)

Labour rate (NEW · per trade partner · rate book)

Product · canonical SKU (NEW · normalised across suppliers)

Supplier + price quote (NEW · adapter cache)

Work order (NEW · cross-cutting · the unit of trade-partner work)

Work order line (NEW)

Existing postcon tables (defect, booking, warranty_event, compliance_cert) gain a nullable tradePartnerId column. Existing Vestra tables (homeowner, property) get folded into the consolidated db with a renamed projection view. Drizzle migrations to be reviewed by Derek before S1 ships.

One JWT shape across all three apps. Issuer is a Hillbrook auth Worker (Cloudflare Access in front for Hillbrook staff, magic-link for trade partners and homeowners). Scope claims drive row-level access — no separate dbs, no separate ACL middleware.

JWT payload

{
  "sub": "usr_01HK…",           // user id
  "iss": "auth.hillbrook.co",
  "aud": "hop.hillbrook.co",
  "role": "trade_partner",     // hillbrook_staff | trade_partner | homeowner | builder
  "scope": {
    "tradePartnerId": "tp_01HK…",  // HSQ Electrical
    "tradeKinds": ["electrical"],
    "clientIds": ["tpc_…", "tpc_…"], // optional whitelist
    "licenceScope": ["REC_VIC"]
  },
  "exp": 1751432800,
  "iat": 1751429200
}

Scope enforcement

Every Drizzle query in the Workers API goes through a scopedDb(jwt) wrapper which mounts row filters at query-build time, not at result-filter time. The wrapper is a single file in @hop/auth · ~80 lines · should be the most-reviewed file in the repo.

// @hop/auth/scopedDb.ts (sketch)
export function scopedDb(jwt: Jwt) {
  return {
    workOrders: () => {
      if (jwt.role === "trade_partner") {
        return db.select().from(workOrder)
          .where(eq(workOrder.tradePartnerId, jwt.scope.tradePartnerId));
      }
      if (jwt.role === "homeowner") {
        // Homeowner sees bookings on their site only
        return db.select().from(workOrder)
          .innerJoin(site, eq(workOrder.siteId, site.id))
          .where(eq(site.homeownerId, jwt.sub));
      }
      if (jwt.role === "hillbrook_staff") return db.select().from(workOrder);
      throw new ForbiddenError();
    },
    // …same pattern for site, defect, booking, etc
  };
}

Magic-link onboarding · trade partner

• Hillbrook staff sends invite from postcon's Trade Directory screen · trade partner email
• Magic link lands user on trade.hillbrook.co/onboard?token=…
• 3-step form: business details + licence claims + first compliance docs upload
• Compliance docs validated by Hillbrook staff (S4) · auto in time (S6)
• JWT issued · trade partner can take first booking

One TypeScript interface every supplier implements. Drop a new adapter into packages/adapters/<supplier>/ and the quote engine, search UI, and POS push all pick it up. No core changes per supplier.

Interface

// @hop/adapters/core/SupplierAdapter.ts
export interface SupplierAdapter {
  readonly id: string;                // 'middys' · 'reece'
  readonly displayName: string;       // "MIDDY's AWM"
  readonly brandHex: string;          // for UI chip
  readonly trades: TradeKind[];       // ['electrical']
  readonly capabilities: Capability[]; // search · stock · order · webhook

  search(q: SearchQuery, ctx: AdapterCtx): Promise<NormalizedProduct[]>;
  getStock(vendorSku: string, ctx: AdapterCtx): Promise<StockQuote>;
  createOrder(order: NormalizedOrder, ctx: AdapterCtx): Promise<OrderResult>;
  // Optional, when the supplier supports webhooks
  verifyWebhook?(req: Request, ctx: AdapterCtx): Promise<WebhookEvent>;
}

Context object

export type AdapterCtx = {
  tradePartnerId: string;       // for trade-discounted pricing
  credentials: SupplierCreds;   // resolved from KV by adapter id + tradePartnerId
  cache: KvCache;               // hop-cache namespace
  logger: Logger;
  fetch: typeof fetch;          // for outbound mocking in tests
};

Normalised product shape

export type NormalizedProduct = {
  productId: string;             // canonical · from product table
  vendorSku: string;
  brand: string;
  name: string;
  unit: 'ea' | 'm' | 'pack' | 'drum';
  priceExCents: number;
  priceIncCents: number;
  stockQty: number;             // -1 = OOS
  leadDays: number;             // 0 = in stock
  branchHint?: string;         // "Williamstown" — for cheapest pickup
  compliance?: Record<string, unknown>;
  fetchedAt: number;
};

Caching · the 80% optimisation

• KV namespace hop-cache with price:<supplierKey>:<vendorSku>:<tradePartnerId> keys
• TTL 15 min for in-stock items · 60 min for OOS items · invalidate on order success
• Cold call → KV miss → adapter search() → reshape into NormalizedProduct → write to D1 price_quote + KV
• Search UI reads KV-first, D1-fallback (for stale stamping), adapter-fallback (only on miss). 5ms typical hit.

Rate limit etiquette

• Each adapter declares a token-bucket in its config · respected by a shared bucket Worker
• If we hit ceiling → cache hit serves stale with a stale-warning flag · UI shows "synced 22 min ago"
• Outbound orders never go through the cache — always live

Example adapter scaffold (Reece)

// @hop/adapters/reece/index.ts
export const reece: SupplierAdapter = {
  id: 'reece',
  displayName: 'Reece',
  brandHex: '#1B4D9B',
  trades: ['plumbing', 'gas', 'hvac'],
  capabilities: ['search', 'stock', 'order'],

  async search(q, ctx) {
    const creds = await ctx.credentials.resolve();
    const r = await ctx.fetch('https://api.reece.com/v1/catalog/search', {
      method: 'POST',
      headers: { Authorization: `Bearer ${creds.token}` },
      body: JSON.stringify({ q: q.text, trade_id: creds.tradeAccount }),
    });
    if (!r.ok) throw new AdapterError('reece', r.status, await r.text());
    const raw = await r.json();
    return raw.items.map(reshape);
  },
  // getStock, createOrder …
};

One Durable Object per active job. All three apps subscribe to it via SSE for the live "Jeremy arrived" / "photo uploaded" / "cert signed" events. Postcon + trade-partner write. Vestra reads.

DO contract

// workers/job-do/JobDurableObject.ts
export class JobDO {
  state: DurableObjectState;
  subscribers: Set<WritableStreamDefaultWriter> = new Set();

  async fetch(req: Request) {
    const url = new URL(req.url);
    switch (url.pathname) {
      case '/subscribe': return this.subscribe(req); // SSE stream
      case '/emit':     return this.emit(req);
      case '/history':  return this.history();
    }
  }

  // Event types: arrival | photo | eta | cert | signoff | warning
  async emit(req: Request) {
    const event: JobEvent = await req.json();
    await this.state.storage.put(`evt:${event.ts}`, event);
    await writeAudit(event);             // D1 audit_event
    for (const w of this.subscribers) {
      await w.write(SSE.format(event));
    }
    return new Response('ok');
  }
}

Routing

• DO id derived from workOrderId (idFromName) · same id reaches the same DO from all three apps
• Trade-partner app emits → DO broadcasts → postcon UI and Vestra UI receive within 100ms
• Subscribers reconnect on tab focus · DO replays from storage since last cursor
• DO hibernates after 6h idle · job audit log lives on in D1

Event shape

export type JobEvent =
  | { kind: 'arrival';  workOrderId: string; tradePartnerId: string; ts: number; geo?: { lat: number; lng: number } }
  | { kind: 'photo';    workOrderId: string; tradePartnerId: string; ts: number; r2Key: string; caption?: string }
  | { kind: 'eta';      workOrderId: string; tradePartnerId: string; ts: number; etaMins: number }
  | { kind: 'cert';     workOrderId: string; tradePartnerId: string; ts: number; certType: CertKind; r2Key: string }
  | { kind: 'signoff';  workOrderId: string; tradePartnerId: string; ts: number; outcome: 'done' | 'rebook' | 'escalate' };

Single Workers API at api.hop.hillbrook.co. REST + SSE. All routes scoped through scopedDb(jwt). SvelteKit apps call the API from server-side load functions and from client actions — same surface for all three.

// Public REST · trade-partner relevant
GET  /v1/me                              // resolved tp + clients + compliance status
GET  /v1/jobs?status=&client=             // scoped to tp
GET  /v1/jobs/:id
POST /v1/jobs/:id/events                  // emit arrival|photo|eta|signoff to DO
GET  /v1/jobs/:id/stream                  // SSE subscribe (proxied to DO)

GET  /v1/clients
POST /v1/clients                          // add platform / external / private

GET  /v1/products/search?q=&trade=        // federated supplier search
GET  /v1/products/:id/quotes              // price strip across suppliers
GET  /v1/inventory                        // own stock by location
POST /v1/inventory/:productId/decrement
GET  /v1/labour-rates
POST /v1/labour-rates                     // rate book CRUD

POST /v1/work-orders                      // create draft
POST /v1/work-orders/:id/lines            // add a line
POST /v1/work-orders/:id/submit           // triggers Procore push + stock decrement

GET  /v1/suppliers                        // marketplace · per-trade
POST /v1/suppliers/:key/connect           // store creds in KV under tp scope

// Postcon / Vestra share the same prefix · different scope claims see different rows.

Versioning

Lock the v1 routes through S4. Breaking changes go to v2 with parallel mount. Vestra's existing API merges into this Worker in S1 — keep current paths under /v1/vestra/… with redirects for one release.

# workers/api/wrangler.toml
name = "hop-api"
main = "src/index.ts"
compatibility_date = "2026-06-01"
workers_dev = false
routes = [{ pattern = "api.hop.hillbrook.co/*", zone_name = "hillbrook.co" }]

[[d1_databases]]
binding = "DB"
database_name = "hop-core"
database_id = "<migrated-id>"     # merge handoffs + tenant-mgmt

[[r2_buckets]]
binding = "EVIDENCE"
bucket_name = "hop-evidence"     # photos · certs · WO PDFs

[[kv_namespaces]]
binding = "CACHE"
id = "<new>"                       # supplier price / stock / session

[[kv_namespaces]]
binding = "SHARED_KV"                # keep — used by Vestra
id = "61aaa876d13448b0b9a5652507fc59f4"

[[durable_objects.bindings]]
name = "JOB_DO"
class_name = "JobDO"
script_name = "hop-job-do"

[[queues.producers]]
binding = "JOBS_Q"
queue = "hop-jobs"                  # supplier sync · procore push

[vars]
ENV = "production"
PROCORE_COMPANY_ID = "598134325611799"

[secrets]                                # via wrangler secret put
PROCORE_OAUTH_CLIENT_ID
PROCORE_OAUTH_CLIENT_SECRET
MS_GRAPH_CLIENT_SECRET
JWT_SIGNING_KEY
SUPPLIER_CRED_ENCRYPTION_KEY

Supplier credentials

Each trade partner stores their own supplier credentials. Stored encrypted in KV under creds:<supplierKey>:<tradePartnerId>, sealed with SUPPLIER_CRED_ENCRYPTION_KEY (AES-GCM). Decrypted in the adapter ctx loader only — never logged, never sent to the client. Rotated by manual ops command for now.

The 88 Glen Iris HWS valve defect — same scenario as the Jeremy mockup. Shows what hits what.

Four sprints of two weeks. Each sprint ships something the team can demo to Tristan. By end of S4 the HSQ pilot is live on real Hillbrook jobs.

Risk register

Open questions for Derek