Turning published law
into knowledge you can
check.

Two workstreams, one platform

Both workstreams do the same fundamental thing: take a document that somebody else authored, and turn it into knowledge a machine can query without losing track of where it came from. One does it for German and EU legislation, the other for insurance documents.

They share Kafka, PostgreSQL, MinIO, Qdrant and Neo4j, and they share no topics, databases or collections. The Legal Knowledge Database is five services and I implemented four of them; the document workstream is three services I extended, one of which I started.

Counts are read from app/data/law_registry.yaml and audit/reports/corpus-certification-ledger.md as of 2026-09-12. The service README states 31 and 51; the registry has moved since, and the registry wins.

The Legal Knowledge Database

Five services in two groups — a three-stage ingestion pipeline and a two-part control plane — over three Kafka topics and four stores, with one rule that makes the whole thing verifiable: exactly one service may write each store.

The ingestion pipeline is the entity producer, the preprocessor and the loader. The control plane is the health service and the dashboard. I implemented four of the five; the entity producer predates legal ingestion and I extended it for EU sources.

That rule is not a convention. It was arrived at by removing a violation. An earlier version of the loader deleted canonical rows, and it could never have succeeded — currency_observations references laws with ON DELETE RESTRICT and is append-only, so the delete was refused every time, after Qdrant and Neo4j had already been cleared and committed. The fix was to delete the code path and rename the replacement so the route states its scope: DELETE /laws/{key}/projections.

The two boundaries

Reading this architecture wrong is easy in exactly one place, so it is annotated three times in the source diagrams. law.structured means canonical PostgreSQL is committed and nothing else — no vector exists, no graph edge exists. law.embedded is the completion boundary: it is published only after both derived stores converge under an exact count fence, and it is the event that makes the preprocessor verify the law without anyone asking it to.

One law, end to end

Eleven stages. Each one either produces evidence, or is measured against evidence produced earlier.

Two orderings in that sequence are load-bearing. The independent source inventory is built before the parser runs, so the denominator used to check the extraction does not come from the thing being checked. And the archive-mirror row is written last of all — after the object has been uploaded, read back, hashed and size-checked — because that row is what the raw-integrity gate treats as evidence. A row that exists has to mean bytes that were verified.

Why four stores

Each store is here because the others cannot do its job. The limitation row is the real justification.

How they stay in step without a distributed transaction

Every derived identifier is a pure function of PostgreSQL content. A Qdrant point id is uuid5(namespace, chunk_id). A graph node is MERGE-d by id, a law node by code. Identity is derived, never generated — so re-running a delivery converges to the same state rather than duplicating it. That single property is what replaces a transaction across a relational store, a vector store and a graph store, and it is why a Kafka redelivery is safe rather than dangerous.

Can we trust what is being served?

The system answers that with fourteen gates and four separate statuses, and it deliberately refuses to answer it with one badge.

Seven gates are required for the aggregate the dashboard shows; the other seven are recorded and displayed anyway, because a measurement nobody can see is not a measurement. All fourteen apply to a German law. Twelve apply to an EU law: fidelity.xml_byte_partition and structure.source_profile are structurally inapplicable to FORMEX and say so in code, with a named reason rather than silence.

What the gates cannot see

A count matching is not proof. A citation misread onto a provision that does exist produces no orphan, moves no count, and fails no gate — which is why a separate human review of citation targets sits alongside the machine gates, and why COMPLETE is defined as machine structural assurance rather than legal review. No law in the corpus claims to be human-certified.

The query path

Deliberately separate from the ingestion path. Nothing here writes a store, and nothing here parses a law.

Retrieval is hybrid and single-round-trip: BGE-M3 produces a dense and a sparse vector from one pass, both are prefetched, and Qdrant fuses them server-side with reciprocal rank fusion. Dense catches meaning — a query for “duty to disclose” reaches the German Anzeigepflicht. Sparse catches exact tokens, which is what a citation like § 19 VVG actually is.

One refusal is worth more than the retrieval design. FlagEmbedding truncates silently past the model's 8192-token window, so the loader counts tokens first and raises for the whole law rather than storing a vector for text the model never fully saw. A silently truncated embedding is undetectable afterwards: it has the right dimensionality, sits in the right collection, and is wrong.

Multi-label chest X-ray classification

A research/prototype medical-imaging classification pipeline — internally named “AI Radiologist”. Five findings, one calibrated decision threshold each, and a Grad-CAM++ attribution map.

Scope: this is a prototype. It is not a medical device, it has no regulatory clearance, it was not clinically validated or deployed, and it does not assist or replace a clinician. The internal project name is recorded here because that is what the repository calls it — it is not a claim about clinical role.

Five findings — atelectasis, cardiomegaly, consolidation, edema and effusion — each with an ICD-10 code and its own decision threshold. The thresholds are Youden’s J optima from a validation set, which is why they differ so widely: cardiomegaly is called positive at 0.130 and effusion only at 0.424. A single global cut-off would have been wrong for every class.

A design decision, separated into fact and interpretation

What the code contains. A per-finding anatomical prior — cardiomegaly centre-left, effusion lower, edema perihilar, each with a boost factor. The mask is boost-only: it emphasises, it never suppresses. The flag controlling it is USE_ANATOMICAL_HINTS = False, commented “DISABLED — trust Grad-CAM fully”, and the surrounding comments state that the model’s attention is the ground truth for localisation and that the hints are soft only.

My reading of it, which the code does not state. An engineering concern is that an anatomical prior could bias localisation towards expected anatomy, so the attribution would tend to agree with the label rather than show what the model actually used. That rationale is my interpretation of the decision — the source documents “trust the model’s attention”, not an argument about explanation bias.

I also read it as the same shape of decision as the legal corpus’s independent oracle — a check that shares the assumption of the thing it checks cannot falsify it. That parallel is my own framing across two codebases, not a claim that either was built with the other in mind.

AI Compliance — what the corpus is for

The customer-facing assessment product. It is the reason the Legal Knowledge Database has to be verifiable rather than merely searchable.

A customer works through a structured questionnaire; a headless browser scans their site for evidence the questionnaire cannot ask for; a knowledge processor reads the questionnaire graph together with the legal corpus and produces a grounded assessment; the result is rendered to a PDF report behind a short-lived token.

Why the corpus has to be verifiable

A compliance report tells an insurance customer whether they meet an obligation, and cites the provision it relied on. If the corpus behind that citation has drifted from what the publisher actually served, the report is confidently wrong and nobody downstream can tell. The gates, the provenance digests and the four separate trust answers exist so that this product’s output is defensible.

Whose work this is: the assessment UI, the backend, the website scan and the knowledge processor were built by colleagues and their repositories are outside the workspace this portfolio was audited from, so no internal detail is drawn. The questionnaire ingestion path is a colleague’s feature living inside a service I implemented — I own the loader, its Kafka handling and its embedding and graph-write layers; the questionnaire service on top of them is marked Integration / shared rather than claimed.

What I built, extended and integrated

Commit shares are from git shortlog on 2026-09-12. A commit count is evidence of weight, not of line ownership, so every specific claim names a file or a commit.

The four-level authorship encoding is consistent across every diagram here: a 2px accent border and a filled corner marker for what I implemented, a thinner border and a hollow marker for what I extended, a hairline for existing platform components, and a dashed hairline for external systems. Use the authorship control in the header to dim everything that is not primary work.

Five problems worth describing

Derived from commits, audit records and code comments. Each one has a constraint, a decision, a trade-off, and a consequence that was actually observed.

What I would keep, and what I would change

Longer form, with context and alternatives for each: ARCHITECTURE_DECISIONS.md.