ContractBot Technical Documentation

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

Version: v1.0 Last updated: —

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.

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.