ICC Rule Engine

ICC Rule Engine is an end-to-end trade compliance platform that validates documentary presentations across ICC rulebooks (UCP600, ISBP745, eURC), international trade frameworks (Incoterms, UNCITRAL, URDG), regional and local regulations, shipping and logistics requirements, sanctions screening, customs/HS code controls, and banking document formats. The system provides a hardened FastAPI backend, a typed admin dashboard, and workflows for multi-tenant governance.

📋 Product Roadmap: For planned features and future enhancements, see ROADMAP.md. For currently implemented features, see docs/feature-matrix.md.

Overview

• Backend: FastAPI 0.111+, SQLAlchemy AsyncSession, Alembic migrations
• Frontend: React 18 + TypeScript 5, Vite, TanStack Query
• Security: API key authentication with admin scope, RBAC-protected routers, audit logging
• Async Processing: Background validation queue, webhook dispatcher, metrics collection
• Rule Taxonomy: Domain/jurisdiction/document-type classification for trade, logistics, sanctions, customs, and banking controls
• Database: PostgreSQL (prod) or SQLite (dev/test) with tenant isolation features

Prerequisites

• Python 3.11+
• Node.js 18+ and npm 9+
• SQLite (bundled) or PostgreSQL instance
• OpenAI API key (only required for LLM-enabled validation tests)

Environment Setup

Backend

1. python -m venv venv
2. source venv/bin/activate (or venv\Scripts\activate on Windows)
3. pip install --upgrade pip
4. pip install -r requirements.txt
5. Copy .env.example to .env (keep it out of git) and update database/API settings. Use DEMO_MODE=true only for local demos; production (ENVIRONMENT=production) must keep DEMO_MODE=false or startup will abort.
6. Run migrations: alembic upgrade head

Start the API server with:

uvicorn app.main:app --reload

Environment note: Production (ENVIRONMENT=production) forces DEMO_MODE=false and raises on startup if the flag is left true; lower environments may toggle it for demos only.

Frontend (Admin Dashboard)

1. cd admin
2. npm install
3. Copy .env.example to .env and set VITE_API_BASE_URL and VITE_ADMIN_API_KEY
4. npm run dev to launch the dashboard on http://localhost:3001

Tenant Invite Email Delivery

Tenant invitations reuse the unified notification service. Provide either a Postmark server token (POSTMARK_SERVER_TOKEN) or a SendGrid API key (SENDGRID_API_KEY) to deliver production email. To keep using custom SMTP credentials, set INVITE_EMAIL_TRANSPORT=smtp and populate SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, and optionally SMTP_FROM. Without any provider configured the service remains in mock mode while NOTIFICATIONS_ALLOW_MOCK=true.

Seed Data

Idempotent scripts are available for Phase C smoke-testing:

• python scripts/seed_rules.py (baseline ICC and trade compliance rules)
• python scripts/seed_rules.py --domain incoterms --jurisdiction us --document-type invoice --version INCOTERMS:2020 --severity fail (example non-ICC import)
• python scripts/seed_versions.py
• python scripts/seed_settings.py

Each script uses AsyncSession and can be rerun safely. Set SEED_RULE_DOMAIN, SEED_RULE_JURISDICTION, SEED_RULE_DOCUMENT_TYPE, SEED_RULE_VERSION, or SEED_RULE_SEVERITY to persist overrides in CI/CD pipelines.

Running Tests

Backend

python -m pytest -q

All suites expect admin-scope fixtures and aligned payloads; unauthorized paths must return 403.

Frontend

cd admin
npm test

Vitest is configured for jsdom with coverage reports emitted to admin/coverage/. Coverage thresholds are enforced in vite.config.ts (statements >=80%, branches >=80%, lines >=90%, functions >=90%).

Continuous Integration & Coverage

• GitHub Actions workflow runs python -m pytest -q and npm test
• Backend coverage gate: >=90% statements/branches
• Frontend coverage gate: thresholds defined in Vite configuration
• Coverage artifacts are uploaded from coverage/ (backend) and admin/coverage/

Branch Naming Convention

• Feature work must branch from main using the format feat/<module>-<slice> (for example, feat/billing-webhooks).
• Choose a module that reflects the product area (billing, admin, rules) and a concise slice describing the change (e.g., webhooks, audit-log).
• Automation jobs rely on this structure to group slices, so avoid additional path segments or uppercase characters.

Phase C Summary

• Async routers for rules, versions, and settings enforce RBAC and pagination
• Admin dashboard tabs (Rules, Versions, Settings) consume the shared api.ts client with typed DTOs
• Seed scripts deliver demo data for Rules, Versions, and Settings domains
• Smoke, async, and webhook tests validate admin scope, schema compliance, and DLQ handling
• CI pipelines enforce coverage and alignment across backend/frontend suites

Additional Documentation

• See docs/ for the end-to-end product documentation set (vision, PRD, SRS, architecture, runbooks, telemetry) and architecture diagrams
• JSON schemas and examples for rule authoring live under docs/schemas/ and docs/examples/
• render.yaml and render.sandbox.yaml contain deployment references
• Tenant onboarding flows and quota management examples are covered in samples/

Support

Contact the Enso Intelligence platform team at support@ensointelligence.com for access requests or operational escalations.

Stripe Billing Setup

To finish Stripe integration:

1. Install dependencies:

   pip install stripe

2. Configure environment variables:

   export STRIPE_API_KEY=sk_live_your_stripe_secret_key
   export STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret
   export STRIPE_PRICE_STANDARD=price_standard
   export STRIPE_PRICE_PRO=price_pro
   export STRIPE_PRICE_ENTERPRISE=price_enterprise
   export STRIPE_CHECKOUT_SUCCESS_URL=https://app.rulengine.com/billing/success
   export STRIPE_CHECKOUT_CANCEL_URL=https://app.rulengine.com/billing/cancel

3. Apply migrations (after selecting the appropriate head if multiple branches exist):

   python -m alembic upgrade <branch>@head

   If the database already contains tables such as notification_preferences, use the merge head (d9da4ab81d0c) and then run the new normalisation migration c8d1f4e2a7e1_normalize_billing_amounts individually.
4. Test webhooks with the Stripe CLI:

   stripe listen --forward-to localhost:8000/billing/webhook
   stripe trigger invoice.paid

5. Validate checkout session URLs by running a test checkout (use the success/cancel URLs configured above).