ContractBot Technical Documentation

Architecture, APIs, monetization engine, AI decision systems, and simulation stack.

Version: v1.0 Last updated: —

Technical walkthroughs

Scroll sideways for the next film — same pattern as a streaming preview row.

API — The Power of Execution

Workers API surface, decisioning, and request flow.

Video missing: pages/videos/ContractBot API_ The Power of Execution_1.mp4 (max 25 MiB per file on Pages).

Architecture — The Execution Gate

Runtime layout: Pages, Workers, KV, R2, Stripe, and safety gates.

Video missing: pages/videos/ContractBot Architecture_ The Execution Gate_1.mp4 (max 25 MiB per file on Pages).

System Scope

AI legal analysis, contract lifecycle, e-sign, invoicing, and VAT-related operations.
Revenue engine with paywall, dynamic pricing, upsell, subscriptions, RL, and meta-controller.
Simulation layers: sandbox, digital twin, investor simulation.

Technical Description

ContractBot is an AI-driven LegalTech platform for SMB/SME organizations. It combines legal document intelligence, contract lifecycle operations, e-signature and invoicing with a self-learning monetization system.

Core flow: Landing -> Scan -> Result -> Checkout -> Success -> Upsell/Subscription.
Legal AI: Risk scoring, issue detection, fixes, and compliance-oriented analysis.
Monetization: Dynamic paywall, contextual pricing, LTV routing, and lifecycle decisions.
Decision engines: Logistic scoring, contextual bandits, RL policies, and meta-controller strategy routing.
Safety: Sticky decisions, baseline fallback, rollback modes, and simulation-before-rollout.
Operations: Funnel analytics, admin alerts, investor metrics, and model diagnostics.

Architecture at a Glance

Frontend: Cloudflare Pages (`/`, `/scan/`, `/result/`, `/success/`, dashboards).
Backend: Cloudflare Workers (API routing, AI decisioning, webhooks, orchestration).
State: KV namespaces for features, lifecycle, bandits, RL Q-table, meta metrics.
Storage: R2 for uploaded files and large artifacts.
Billing: Stripe one-time + subscriptions + webhook feedback learning.
Automation: Cron aggregation, retention tasks, and model-support jobs.

Architecture Diagram

High-level runtime and decision flow.

graph TD
  A[Landing / Scan / Result] --> B[Cloudflare Workers API]
  B --> C[Decision Layer: Score + Bandit + RL + Meta]
  C --> D[Checkout / Subscription via Stripe]
  D --> E[Webhook Feedback]
  E --> C
  B --> F[KV State: Features, Lifecycle, Models, Q-table]
  B --> G[R2 Upload Storage]
  F --> H[Analytics / Alerts / Dashboards]
  F --> I[Simulation Sandbox + Digital Twin + Investor Sim]

Landing -> Scan -> Result -> Checkout
         -> Webhook feedback -> Model updates
         -> Decision engines (Bandit/RL/Meta)
         -> Analytics + Simulation

Integrator Quick Block

Copy ready-to-use base URLs and environment summary.

API base: https://contractbot.eu

Environment summary:
- Runtime: Cloudflare Workers + Pages
- Storage: KV (features/models/lifecycle), R2 (uploads)
- Billing: Stripe (one-time + subscription + webhook)
- Scheduling: Cron jobs (aggregation + retention)

One-Click Onboarding (Developers)

Copy the commands below to validate integration in minutes: health, decisioning, and admin funnel.

1) Health check (public)

curl -sS "https://contractbot.eu/api/health"

2) Decisioning (public, JSON)

curl -sS -X POST "https://contractbot.eu/api/meta/decision" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"dev_demo_user","score":78,"segment":"WARM","device":"desktop","session_id":"dev_demo_session"}'

3) Admin funnel (requires admin key)

curl -sS "https://contractbot.eu/api/admin/funnel" \
  -H "x-admin-key: YOUR_ADMIN_KEY"

Auth summary:
- Public endpoints: no key required (for example /api/health, /api/meta/decision)
- Admin endpoints: x-admin-key header required
- JSON endpoints: use Content-Type: application/json

Documentation Set

README_TECH.md — full technical architecture and system behavior.
PRODUCT_CAPABILITIES.md — product capability map for product/sales/investors.
API_REFERENCE.md — high-level API endpoint reference.
docs/INDEX.md — role-based documentation entrypoint.
docs/DEV_VIDEO_SCRIPT.md — developer video explanation script.
docs/DEPLOYMENT.md — CI/CD, staging, production, and rollback operations.
Privacy Policy — GDPR-oriented data handling and user rights.
Terms of Service — service scope, user responsibilities, and liability limits.
Data Processing Agreement (DPA) — processor obligations and safeguards.
AI Disclaimer — no legal advice and model limitations.
Enterprise onboarding — procurement-ready compliance consulting.

Operational Areas

Cloudflare Workers for APIs, orchestration, webhooks, and decisioning.
Cloudflare Pages for frontend delivery.
KV namespaces for features, models, lifecycle, RL/bandit state, and aggregates.
Stripe for one-time and subscription billing flows.
Compliance Score API for B2B readiness, weak-point detection, and enterprise upsell routing.
Behavior Heatmap for anonymized attention, click, scroll, hover, and intent analytics.

Link Health (Release Checklist)

Manual smoke test before release: open each URL and confirm expected content (not fallback landing).

/tech-docs/ opens technical docs page.
/consulting/ opens enterprise onboarding support.
/behavior-dashboard opens the admin heatmap viewer.
/investor-dashboard opens investor dashboard (no redirect loop).
/privacy, /terms, /dpa, /ai-disclaimer open legal pages.
API walkthrough video opens and is playable.
Architecture walkthrough video opens and is playable.
Documentation links (/README_TECH.md, /PRODUCT_CAPABILITIES.md, /API_REFERENCE.md, /docs/INDEX.md, /docs/DEV_VIDEO_SCRIPT.md) resolve to expected doc content (not landing fallback).

Quick CLI check (status + final URL):
curl -I https://app.contractbot.eu/tech-docs/
curl -I https://app.contractbot.eu/investor-dashboard
curl -I https://app.contractbot.eu/privacy
curl -I https://app.contractbot.eu/terms
curl -I https://app.contractbot.eu/dpa
curl -I https://app.contractbot.eu/ai-disclaimer

Stripe & Access Security Gate

Stripe is a checkout lock, not a code vault. Access control must be backend-only.

User clicks pay
-> Stripe Checkout
-> Stripe webhook confirms payment
-> Worker stores entitlement (paid/plan/features)
-> API validates entitlement before returning full result

Never grant access from frontend-only state.
Map Stripe price_id to features only in Worker/backend.
Use webhook as source of truth for paid/subscription status.
Keep full results in Worker/KV/R2; frontend shows preview before unlock.
Keep API keys/secrets in Cloudflare secrets, never in frontend.
Enforce entitlement checks and rate limits per tenant/user/key.
Keep private pricing logic and internal admin implementation non-public.

Public Exposure & Security Policy

Public (Allowed)

README_TECH.md
API_REFERENCE.md
PRODUCT_CAPABILITIES.md
docs/INDEX.md
docs/DEV_VIDEO_SCRIPT.md

These files are part of the product surface for onboarding, integrations, and enterprise demos.

Never Public

/workers/*
/src/*
/.env
/wrangler.toml
/node_modules/*
/admin/*
Stripe secret keys
API keys / tokens
private pricing logic
internal prompts / AI configs

Rule

Public documentation describes integration behavior, not backend implementation.

Release Security Check

✔ Docs return correct content (not fallback)
✔ Protected paths return 404
✔ No secrets in public responses
✔ Stripe keys are server-side only
✔ API requires authentication

Mandatory release gate:
BASE_URL="https://app.contractbot.eu" npm run check:release

Deploy is valid only if:
- check:docs passes
- check:security passes
- check:entitlement passes
- protected paths return 404/403
- public docs return real content
- no secret signatures are leaked