All work Case study 02 / 04

ClearClause

Document risk intelligence for consumer finance and property agreements — every finding traced back to the exact wording that produced it.

Type
Full-stack application
Status
Active development
License
MIT
Stack
FastAPI · Celery · PostgreSQL · Redis · Next.js 15 · Qdrant · OpenTelemetry
Links
Source
01 — Context

The information is in the document. It just isn’t readable.

People agree to loan, subscription, credit-card, rental and property terms they haven’t read, and couldn’t parse if they had: processing fees deducted from the disbursed amount, foreclosure charges, free trials that convert silently, lock-ins, deposits that are never coming back.

A general “ask an LLM about your PDF” tool can summarise that. But it can’t guarantee the same answer twice, and it can’t show you why it said what it said — and for a document you are about to sign, those are the two things that matter.

02 — Approach

Deterministic first: rules decide, the model explains.

A rule engine and per-type analyzers are the source of truth. Every finding cites the clause that triggered it, and the same document always yields the same findings.

The LLM layer sits strictly downstream. It rephrases findings and answers questions over facts that already exist; it cannot introduce a finding, and Q&A refuses to answer when retrieval comes back empty. The AI layer is off by default — everything else works without it.

The repository’s contribution rule says it plainly: a change that lets the LLM originate a finding, rather than explain one, will not be merged.

03 — Architecture

A modular monolith, a worker, and a chain of idempotent stages.

ClearClause architecture A Next.js frontend calls a FastAPI API over REST with a JWT cookie. The API writes to PostgreSQL and to storage, either a local directory or S3, and enqueues a chain on Redis. A Celery worker runs the pipeline: OCR, classify, segment, analyze, score, and PDF report, each one task and one trace span. Optional AI stages chunk and embed into Qdrant, and write a summary with the Groq LLM. Next.js frontendApp Router · React 19 REST · JWT FastAPIasync · Pydantic v2 PostgreSQLAlembic Storagelocal dir · S3 Redisbroker · limits Celery workerscales out pipeline — one task + one span per stage OCR Classify Segment Analyze Score PDF report rules decide here — each finding bound to its clause AI_MODE Chunk + embedJina → Qdrant · BM25 + RRF Summary · Q&AGroq LLM · explains, never decides
Fig. 1The accented path is the deterministic core. Dashed stages are optional and soft-failing: an outage costs the summary, not the document.
  • Layered by concern. Routes → services, one per pipeline concern → repositories, which own all persistence → SQLAlchemy models. Worker tasks call the same services as the API.
  • Stages talk through contracts. Pydantic types in app/contracts are the stable seams between stages — not each other’s models.
  • Upload returns immediately. Processing runs off the request path across dedicated queues for OCR, analysis, reports and AI.
04 — Engineering

Built to be retried, audited and attacked.

  1. Idempotent, retry-safe stages

    Every stage is an independent Celery task with its own OpenTelemetry span and status write. Repository writes are replace-by-document, so a retry or a reprocess reproduces exactly the same state. A stage failure marks the document FAILED and stops the chain.

  2. Classification that admits doubt

    A rule-based classifier over 26 document types — weighted keyword signals plus filename hints — yields a confidence and a routing action: automatic at ≥ 0.90, confirm with alternatives shown at ≥ 0.70, otherwise the user picks. It stays correctable afterwards.

  3. Selective OCR

    The default provider reads the PDF’s text layer and only rasterizes pages that lack one, so the common case skips OCR entirely. Mean OCR confidence is recorded and surfaced when it is low.

  4. Hybrid retrieval, built in-repo

    BM25 and vector search fused with Reciprocal Rank Fusion, plus SQL entity lookup for factual questions and a 26-entry knowledge pack of RBI, IRDAI, RERA and Consumer Protection regulations — routed by rule-based intent detection.

  5. Uploads are hostile until proven otherwise

    Magic-byte sniffing — the extension is never trusted — a byte cap, and an independent page cap, because a small compressed PDF can hold thousands of pages and OCR memory scales with pages, not bytes.

  6. Production refuses to start unsafe

    With ENV=production the app won’t boot if the JWT secret is still the default, cookies aren’t Secure, or any CORS origin is plain HTTP. The check lives in settings validation, so it covers the API, the worker and migrations alike.

05 — Tradeoffs

What I chose, and what it cost.

Why not let an LLM read the document and report the risks?
It can’t promise the same findings twice, and it can’t point at the clause that justifies one. Rules can do both. The cost: coverage is bounded by what the analyzers know — six type-specific analyzers today; other types fall back to the generic rule engine.
Why does token revocation fail closed while rate limiting fails open?
They protect different things. If revocation can’t be verified, accepting the token could let a stolen session through, so it is refused. If the Redis-backed limiter is unreachable, refusing every request would take login down with it — so traffic passes and a degradation counter increments.
Why lock accounts when there is already an IP rate limit?
An IP-keyed limiter does nothing against credential stuffing spread across many IPs at one account. Ten failures in fifteen minutes locks the account, whatever the source.
Why never retry a task that hit its time limit?
A document that blew the soft time limit will blow it again. Retrying turns one doomed task into three while everyone else queues behind it. Transient failures retry with backoff; time-limit breaches don’t.
Why a modular monolith rather than services?
Clean module boundaries without the microservice tax. The one seam that needs to scale — document processing — is already a separate worker that scales out; splitting it per queue waits until throughput demands it.
06 — Results

Where it stands.

MeasureState
Pipeline: upload → OCR → classify → analyze → score → PDF reportimplemented
Backend tests — unit, integration, end-to-end130
Document types classified26
Type-specific analyzers — loan, subscription, credit card, rental, sale deed, patta6
Regulation knowledge pack entries26
CI — ruff, pytest, tsc, ESLint, Docker build, Trivy scanGitHub Actions

Active development. The AI layer — summaries and retrieval-grounded Q&A — is implemented but disabled by default, and needs third-party API keys. Not yet built: MFA, email verification, password reset, audit logging, per-tenant isolation, response caching, streamed answers. ClearClause produces informational analysis; it is not legal or financial advice.