Architecture | SmallBiz Ops Copilot

Service Architecture - SmallBiz Ops Copilot

SmallBiz Ops Copilot is a bounded, approval-safe support control tower. The architecture separates the implemented pilot path from production capabilities that still require customer-specific design and verification.

Current Runtime

flowchart LR
    OC["Openclaw\nnormalized event"] -->|"signed webhook"| MW["Cloudflare Pages\nmiddleware and validation"]
    MW --> D1[("Cloudflare D1\nqueue and audit state")]
    OP["Operator browser"] --> UI["Queue, risk board,\nreview pack"]
    UI --> API["Pages Functions\ntriage, draft, approval"]
    API --> D1
    API -->|"optional, operator invoked"| LLM["OpenAI or Gemini"]
    API -->|"fallback"| TPL["Deterministic templates"]
    API -->|"approved handoff"| MB["Maltbook webhook"]
    MB -.->|"outside current evidence boundary"| CC["Customer channel"]

The dotted edge is intentionally not a product claim. The repository records Maltbook webhook acceptance but does not verify delivery to a marketplace, social network, email inbox, or end customer.

Trust Boundaries

Boundary	Implemented control	Current limitation
Inbound	Openclaw shared-secret signature and normalized schema	No replay timestamp/nonce window or direct channel adapter
State	D1 schema for merchant, ticket, message, draft, SLA, and action logs	Default merchant pattern is not tenant isolation
Triage	Operator-triggered deterministic rules and logged overrides	Not a policy engine or autonomous classifier
Draft	Operator-triggered provider call, BYOK support, template fallback	No tenant prompt policy or formal model evaluation set
Approval	Named operator value is required and logged	Operator ID is not authenticated identity
Handoff	Maltbook configuration gate and explicit success/pending response	No customer-channel receipt or exactly-once outbox
Public data	Configuration readiness only; context is operator-facing	Must not drive automated refund or fulfillment decisions

Implemented Components

public/: queue, risk, review, and approval workspace.
functions/integrations/openclaw/webhook.js: only accepted live inbound path.
functions/ingest/[channel].js: disabled legacy path returning 410.
functions/tickets/: ticket review, triage, draft, feedback, status, and approved handoff.
functions/dashboard/: queue pressure, runtime posture, handoff risk, and operator evidence.
functions/_lib/product-contract.js: machine-readable product and delivery boundary.
migrations/ and seeds/: local D1 schema and synthetic review data.

Pilot Deployment

Resource	Purpose	Guard
Cloudflare Pages	Static operator UI	No secrets in client assets
Pages Functions	Request validation and workflow APIs	Explicit integration failures
D1	Pilot queue and audit records	Customer-approved retention and deletion required
Cloudflare secrets	Openclaw, Maltbook, and optional model credentials	Separate local/staging/production values
External model provider	Optional draft assistance	Operator invocation and deterministic fallback
Maltbook webhook	Approved workflow handoff	Acceptance is not customer-channel delivery

Production Target

flowchart LR
    IDP["Customer identity provider"] --> GW["Authenticated API gateway"]
    SRC["Approved support channels"] --> ADP["Tenant-scoped adapters\nsignature + replay guard"]
    ADP --> Q["Durable queue / outbox"]
    Q --> CORE["Tenant-scoped workflow service"]
    GW --> CORE
    CORE --> DB[("Tenant-isolated data\nretention + deletion jobs")]
    CORE --> MODEL["Policy-gated model adapter"]
    CORE --> APPR["Authenticated approval service"]
    APPR --> OUT["Delivery adapter + receipt verification"]
    OUT --> AUDIT["Immutable delivery and audit evidence"]

Promotion requires tenant authentication and authorization, rate limits, replay protection, an outbox or equivalent retry design, verified delivery receipts, privacy controls, monitoring, incident ownership, and customer-specific acceptance tests.

Failure Semantics

Missing Openclaw or Maltbook configuration produces explicit degraded/blocked status.
Invalid or duplicate inbound events are rejected.
Model failure falls back to deterministic draft text; it does not approve or publish.
A failed Maltbook call returns 202 with pending delivery evidence after the local workflow record is committed.
customer_channel_delivery_confirmed remains false in both success and failure responses.

Cost And Scope Controls

Start with one signed intake and one handoff target.
Keep model use operator-triggered and allow deterministic fallback.
Do not add queues, object storage, analytics, or direct channel adapters until the pilot requires them.
Agree usage limits, data retention, and support ownership before external testing.

Verification

npm run verify
python3 scripts/validate_repository_surface.py
python3 scripts/validate_architecture_blueprint.py
npm run smoke:local

The sellable unit is a customer-specific Secure Workflow Pilot. It is not a revenue, response-time, or automation guarantee.