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.
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.
A modular monolith, a worker, and a chain of idempotent stages.
- 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/contractsare 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.
Built to be retried, audited and attacked.
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
FAILEDand stops the chain.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.
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.
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.
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.
Production refuses to start unsafe
With
ENV=productionthe app won’t boot if the JWT secret is still the default, cookies aren’tSecure, or any CORS origin is plain HTTP. The check lives in settings validation, so it covers the API, the worker and migrations alike.
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.
Where it stands.
| Measure | State |
|---|---|
| Pipeline: upload → OCR → classify → analyze → score → PDF report | implemented |
| Backend tests — unit, integration, end-to-end | 130 |
| Document types classified | 26 |
| Type-specific analyzers — loan, subscription, credit card, rental, sale deed, patta | 6 |
| Regulation knowledge pack entries | 26 |
| CI — ruff, pytest, tsc, ESLint, Docker build, Trivy scan | GitHub 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.