Project Guide | SmallBiz Ops Copilot

SmallBiz Ops Copilot

Approval-safe support operations control tower for a bounded pilot. It combines a D1-backed queue, operator-invoked triage, assisted draft preparation, mandatory human approval, and an auditable Maltbook webhook handoff.

This repository does not claim autonomous customer support or verified customer-channel delivery. Direct channel ingest is disabled; the only live inbound path is a signed Openclaw webhook. The current outbound boundary ends at a Maltbook webhook handoff.

System Overview

A reviewable control surface for teams that need to organize support work without handing decision authority to a model.

Evaluation Path

• Start here: Open the queue, inspect the highest-risk ticket, and read the approval gate before generating a draft.
• Trace the boundary: Confirm direct ingest returns 410, signed Openclaw intake is accepted, and the approval response states that customer-channel delivery is not confirmed.
• Local demo: Run local migrations and npm run dev, then inspect the Cloudflare Pages Functions surface.
• Checks: Run npm run verify; it covers Biome lint and Node tests.

Technical Notes

• Technical guide summarizes the system scope, first files to inspect, verification commands, and known boundaries.
• Quality notes lists the local checks, CI surface, and release expectations for this repository.
• Enterprise readiness notes outlines security, data, operations, integration, and handoff expectations.

What's in here

• Runtime: Cloudflare Pages Functions in functions/ + inbox/dashboard UI in public/
• Data: D1 migrations and seeds in migrations/ and seeds/
• Docs: docs/product/PRD.md, openapi.yaml, schema.sql

Prerequisites

• Node.js 22+
• Cloudflare account
• Wrangler CLI (npm i)

Configure D1

wrangler d1 create smallbiz_ops_copilot

Set database_id in wrangler.toml:

[[d1_databases]]
binding = "DB"
database_name = "smallbiz_ops_copilot"
database_id = "YOUR_DATABASE_ID"

Secrets

Set in .dev.vars for local dev and via Wrangler for production:

• OPENAI_API_KEY (optional server fallback key)
• ALLOW_SERVER_OPENAI_KEY (must be true to enable server key)
• OPENCLAW_WEBHOOK_SECRET (webhook signature check)
• MALTBOOK_WEBHOOK_URL (required for the approved webhook handoff)
• Optional Korean public-data enrichment keys: BIZNO_API_KEY, DATA_GO_KR_SERVICE_KEY, SMALLBIZ_365_API_KEY, FAIR_DATA_API_KEY, CONSUMER_PRICE_API_KEY, LOCAL_CURRENCY_API_KEY, KMA_API_KEY, AIRKOREA_API_KEY

The optional public-data readiness route is aligned with public-apis-4Kr and reports configured provider coverage without returning secret values.

Run Migrations + Seed

npm run db:migrate:local
npm run db:seed:local

Quick Start

npm install
npm run db:migrate:local
npm run db:seed:local
npm run dev

Quality Checks

npm test
npm run smoke:local
npm run debug:local

Operator fast path

1. GET /health — confirm the runtime is up before reading any queue claims
2. GET /dashboard/proof-map — read the front-door route map before diving into the queue
3. GET /integrations/public-apis — confirm optional merchant, market, pricing, and operating-risk enrichment readiness
4. GET /dashboard/ops-brief — read the compact ops posture first
5. GET /dashboard/review-pack — inspect the approval gate and operator proof path
6. GET /dashboard/owner-handoff-board — confirm shift handoff posture
7. GET /dashboard/outbound-risk-board — check the handoff-risk boundary before treating work as ready

Disabled ingest boundary

POST /ingest/{channel} is intentionally disabled and returns 410.

That is not an accidental gap. This repository is an approval-safe support control tower, not a collection of direct marketplace or social-channel connectors. The signed POST /integrations/openclaw/webhook route is the only live inbound path.

API Endpoints

• POST /ingest/{channel} - Deprecated ingest route (currently disabled / returns 410)
• GET /tickets - List tickets (filter by status, priority, search)
• GET /tickets/{id} - Ticket detail
• POST /tickets/{id}/triage - Triage a ticket
• POST /tickets/{id}/draft - Generate AI draft
• POST /tickets/{id}/approve-send - Record approval and publish a Maltbook handoff; the route does not verify customer-channel delivery
• GET /dashboard/kpi - KPI metrics
• GET /dashboard/alerts - Alert queue
• GET /dashboard/brief - Command brief
• GET /dashboard/proof-map - Front-door proof route map
• GET /integrations/public-apis - Korean public API enrichment readiness
• GET /dashboard/ops-brief - Ops readiness brief
• GET /dashboard/review-pack - Approval gate summary
• GET /dashboard/owner-handoff-board - Shift handoff board
• GET /dashboard/outbound-risk-board - Outbound risk status
• GET /health - Health check

Key Features

• Direct channel ingest is disabled; signed Openclaw intake is required
• Triage and draft generation are operator-invoked, not autonomous
• Every outbound handoff requires a named operator approval
• Maltbook confirms webhook handoff only, not customer-channel delivery
• Draft assistance can use OpenAI or Gemini and falls back to deterministic templates
• BYOK runtime key support via sidebar
• SLA alert queues, trend charts, auto-refresh
• Keyboard shortcuts: Ctrl+Enter approved handoff, Shift+R draft, Shift+T triage

Pilot Offer

The sellable unit is a Secure Workflow Pilot, not an off-the-shelf autonomous support SaaS. A pilot adapts one support queue, one signed intake contract, one approval policy, one handoff target, and one audit/export runbook. Success metrics are agreed from a customer baseline; this repository does not guarantee time savings, conversion, or revenue.

Discuss a private Secure Workflow Pilot

Deploy

npm run deploy:cloudflare

Cloud + AI Architecture

• Cloud + AI architecture blueprint
• Machine-readable architecture manifest
• Validation command: python3 scripts/validate_architecture_blueprint.py

Enterprise Productization

• Product operating model defines the product scope, trust boundary, operating checks, and service path for this repository.

Service Architecture

• Service architecture defines the cloud resources, account information, cost controls, and production guardrails needed to turn this repo into a scoped service without publishing public financial assumptions.