Shipped v1
A tender-response engine built around one rule: never guess on compliance.
Defense tenders arrive as hundreds of numbered requirements. Building the compliance matrix by hand takes days — and a single careless "Comply" is a contractual claim. This system automates the drudgery while making the dangerous parts impossible to automate.
What changed
- Before
- Each compliance matrix was built by hand, a row at a time, over days of expert time.
- Now
- Tender PDF in, reviewed matrix and DOCX out, with every row traced to its source clause.
Verified build figures
July 2026 (v1 production-readiness pass)
- Tests passing
- 37/37
- Routing stages
- 6
- API endpoints
- 10
- Statuses, collapsed at export
- 7 → 4
End-to-end verified: create case → upload → extract → review → approve-to-cache → generate DOCX → download. Ships as a single Docker container serving API and frontend, with 6 vehicle platform spec sets and 11 response templates seeded. Supabase-backed auth; JSON-file storage by deliberate v1 scope, behind interfaces ready for Postgres/S3.
The problem
Every tender response meant manually reading hundreds of clauses, deciding Comply / Partial / Non-Comply per row, writing responses, and assembling a formatted matrix — days of expert time spent mostly on requirements the company had already answered in previous bids.
The constraint
A compliance matrix is a legal representation to a procurement authority. Speed was worthless without defensibility — so the architecture optimizes for "provably correct or explicitly flagged," never "probably right."
The pipeline.
- Case created — platform selected, tender PDF locked as case bible
- Page-wise extraction with numbered-clause detection
- Hierarchy normalization — refs, leaf detection, categories
- Stage 1 · Approved cache lookup (human-approved answers)
- Stage 2 · Safety hold — ballistic / payload rows frozen for review
- Stage 3 · Numeric spec check against platform data
- Stage 4 · Deterministic platform capability check
- Stage 5 · Response template match
- Stage 6 · Conservative AI stub → Manual Review Needed
- Evidence-or-downgrade validation, human review, cache write-back
- DOCX generation — clean matrix + traceability appendix
Six decisions that define the system.
The engineering here is mostly restraint: deciding what the machine must never answer, and making that impossible rather than merely discouraged.
- 01
AI runs last — and in v1, not at all
Requirement rows route through six stages in strict order: approved cache → safety hold → numeric spec check → platform capability check → template match → AI. The AI stage is a conservative stub that outputs "Manual Review Needed" — no model call is made anywhere in v1.
Why not the obvious alternative
The obvious 2026 build is "feed the tender to an LLM." But a hallucinated "Comply" on a ballistic spec is a contractual claim, not a typo. Deterministic checks answer what can be proven; everything else is honestly routed to a human. The AIResponder interface exists so a real model can slot in later — behind the same guardrails, never in front of them.
- 02
A safety hold that no automation can override
Rows touching ballistic protection levels (VPAM, STANAG, CEN 1063, BR4–7), payload, upgraded GVW, suspension, brakes, or armoured configuration are held at Manual Review Needed — always — unless a human-approved cache entry explicitly covers them.
Why not the obvious alternative
These are the rows where a wrong answer costs a contract or worse. The design question wasn't "can we automate this?" — it was "what must never be automated?" The safety hold runs second in the pipeline, before any check that could mark a row compliant.
- 03
No evidence, no "Compliant"
A post-validation layer enforces evidence-or-downgrade: any row marked Compliant without an attached evidence trail is automatically downgraded. The exported DOCX carries a traceability appendix mapping every matrix row to its source document, page, and clause.
Why not the obvious alternative
Compliance matrices fail audits on unsupported claims, not missing ones. Making evidence structurally mandatory means the output is defensible in front of a procurement officer, not just impressive in a demo.
- 04
Human review compounds into a response library
When a reviewer approves rows, they write back into a normalized-key approved cache — which is stage one of the pipeline. The next tender that asks the same question gets the human-approved answer instantly.
Why not the obvious alternative
The fashionable version is fine-tuning a model on past responses. The cache achieves the compounding without training cost, drift, or opacity: every cached answer was explicitly approved by a person, and the cache file itself is the single most valuable backup artifact.
- 05
The tender is locked as an immutable "case bible"
On upload, the source PDF is locked per case. Extraction, review, and export all trace back to it; parsed pages are kept as an auditable intermediate so even dropped clauses remain inspectable.
Why not the obvious alternative
Compliance work collapses when the source document can silently change mid-review. Immutability makes every downstream edit accountable to one fixed reference — the same discipline as a contract redline.
- 06
Limitations are documented, not hidden
No OCR — scanned PDFs are flagged as possibly scanned rather than guessed at. Narrow numeric coverage by design: units outside the verified set route to manual review. Every known parsing edge case is written down in the project docs.
Why not the obvious alternative
A system that guesses at the 5% it can't parse poisons trust in the 95% it can. Flagging over guessing is what makes reviewers actually rely on the tool — the failure modes are part of the spec, not a surprise.
Stack
- Python / FastAPI
- PyMuPDF
- python-docx
- React 18 + Vite
- Supabase Auth
- Docker
- pytest
Want the deeper walkthrough?
I can demo the full flow live — tender PDF in, reviewed compliance matrix and DOCX out — and walk through the routing code and safety-hold logic on screen.