Dentra

Before the story, the shape. Everything after this is a consequence of the boundary drawn here.

Dentra did not start from an empty repository. It began by forking a working foundation from an earlier product in the same family: guards, interceptors, exception filters, an upload module, session services, a config-driven data table. The transplant took about 48 hours and bought roughly four months of work.

It also introduced a category of debt that took the rest of the project to name. Some of the inherited code was a decision; some of it was an artifact of a different product with a different architecture, still running because it worked well enough not to demand attention. A URL builder that reassembled paths from four environment variables was not a design, it was glue from a filesystem-only predecessor.

The lasting change was not a refactor but a question added to every review: did we decide this, or did we receive it? Inherited code is held to a different standard, because keeping it is a choice being made silently every day.

The clinical domain is twenty-five tables and seventeen enumerated types, and the parts worth describing are the ones where a modelling decision prevented a class of mistake rather than merely stored a fact.

An appointment moves through eight states: scheduled, checked in, waiting, in treatment, completed, cancelled, no show, rescheduled, with a separate outcome recorded when it ends. The current state lives on the appointment, and every transition is also written to an event log that records what changed, from which state to which, the queue number at the time, and the queue positions before and after a reorder. That last detail is the one that earns the table. A receptionist moves an urgent patient up the queue and someone who arrived earlier waits longer, and the question that follows is not answerable from a status column. It is answerable from an ordered record of who moved, when, and past whom.

The waiting room has a display screen, and it is deliberately the thinnest surface in the system. It shows queue numbers and nothing else: no names, no phone numbers, no procedure. It authenticates, polls every ten seconds, and fails silently on a poll error because a blank panel in a public room is better than an error message in one. A screen in a room full of strangers, attached to a database of medical records, is a place where the safest design is the one that has almost no data to leak.

Procedures record where in the mouth they happened as either a quadrant or the whole mouth, with the quadrant left null in the second case. Modelling it as two location kinds rather than an optional quadrant field means a cleaning cannot accidentally carry a quadrant and a filling cannot accidentally lack one. Medical conditions and allergies follow a catalogue and instance pattern: a clinic-wide list of known conditions, and per-patient records that reference it, so two spellings of the same allergy cannot coexist in one patient's chart.

Treatment decomposes rather than flattening. A plan holds items, items are delivered across sessions, sessions produce the treatments actually performed, and treatments consume materials from inventory. Each level exists because clinics quote at one level, schedule at another, and bill from a third.

The obvious architecture for a clinic SaaS is row-level multi-tenancy: one database, a tenant column everywhere, one instance to operate. It is cheaper to run and far cheaper to deploy. It was rejected, because careful query review reduces the risk of a cross-tenant leak but never eliminates it, and physical separation makes that failure structurally impossible rather than carefully avoided.

The cost was paid in operations rather than in code. Every clinic is a separate deploy, migration run, backup and credential set. There is no cluster, no rolling deploy, no shared cache to hide behind, and onboarding is a procedure rather than a signup form.

One dividend was unplanned. Because every customer is a separate deployment, the first clinic to receive a release is a natural canary, which is the staged-rollout capability blue/green infrastructure exists to provide. It arrived for free and is the reason that infrastructure has never been needed.

Ahead of the first clinic going live, the operational half of the system did not exist. Storage, deployment identity, boot gates, observability and the operator tooling were designed and built in days rather than sequentially over months, which is why they share a vocabulary.

Storage was the deepest piece. The inherited layer treated the filesystem as the database and had no concept of where bytes lived that was separable from what they were called. The rebuild split four fused concerns: a provider contract owning where bytes live, a key builder owning naming, a metadata table owning what is known about a file, and visibility owning who may see it.

The most consequential finding came from reading Cloudflare R2's access model directly. The original design used a private key prefix inside a single bucket. It was internally consistent and had been reviewed as correct, and it could not work: R2 public access is bucket-wide, so a prefix is not an access boundary however carefully it is applied. The boundary moved to the bucket, and the provider now refuses to boot on a single-bucket configuration rather than falling back to it.

The same phase established deployment identity as immutable. The deployment identifier is written into every object key and persisted across several tables, so it can never change once real data exists, while the clinic's display name is referenced by nothing and is safe to edit at any time. Conflating those two, which is the natural thing to do since both are the clinic's name, would have made the first rebrand a data migration.

By this point a private framework already existed, extracted from a sibling product to stop three codebases reimplementing authentication, permissions and audit. Reading the actual chronology produced the most uncomfortable finding of the project: the framework had been extracted from a codebase that was four days old, single-tenant, with no production deployment, no object storage and no operations story.

Almost every capability worth sharing was written afterwards. Storage, deployment configuration, boot gates, request correlation, database observability and the operator CLI all postdate the framework's creation. It was not behind because it was built badly. It was behind because it was built first.

The measurements that followed were worse than the diagnosis. One package had zero consumers anywhere. Four modules in one adapter had none, and two of those had been actively reimplemented by the single product that had adopted the framework elsewhere. Exactly one duplicate implementation had ever been deleted across the entire family.

That last number reframed the strategy. Package count measures nothing; the only metric that proves the mechanism works is how many duplicates have actually been deleted. And when a product routes around a capability, the capability goes on trial rather than the product.

Extraction was reordered around evidence. A capability is only extracted once real duplication exists, and it is only finished once the code it replaced has been deleted. Two have completed that cycle.

File content validation consolidated four independent implementations, roughly six hundred lines doing one job. Adoption exposed a flaw in the product rather than the framework: the content check was the first gate on the upload path, so its signature table was silently both verifying that bytes matched the declared type and deciding which types the surface accepted. The fix required no framework change at all, only separating what the product had merged.

Permission evaluation unified the semantics used by the backend guard and the web client, so both runtimes now call the same functions. It also corrected a framework default: an empty requirement list had evaluated as satisfied, which on a security gate means an accidentally-empty requirement admits everyone. It now fails closed. The deciding evidence was that the only existing consumer had already written a compensating workaround with a comment explaining the framework was wrong, which is a bug report the framework never received.

One earlier conclusion was reversed outright. A review had recommended retiring a zero-consumer package as speculative. Attempting to adopt it showed the opposite: it had anticipated a genuine behavioural difference between two products that neither had reported. Zero consumers is evidence that adoption failed, not that the design is wrong.

Several investigations changed the architecture without necessarily producing features. They are listed because the reasoning was the deliverable.

Every system this size has them, and the ones nobody mentions are the ones a reader discounts hardest. These are tracked in the repository, not just here.

Distinct from the lessons above, which are rules that came out well. These are the calls I would make differently starting over.

The ongoing work is turning proven capabilities into ZothKit while keeping product-specific concerns permanently in Dentra. Clinical domain logic, schema, migrations and tenancy stay in the product; configuration, identity, storage, observability and access control are the shared surface.

Near-term priorities are continuous integration, streaming file I/O before extraction rather than after, session revocation, and a composable platform bootstrap so the security reasoning currently expressed as imperative startup code can reach the sibling products that lack it.

The measure of success is not the number of packages. The oldest product in the family took roughly four months to reach production hardening and Dentra took about seven weeks. The goal is to make the next product's number days, by shipping the container, the deployment stack, the backup tooling, the boot gates, observability and storage as a starting point rather than as things each product acquires one incident at a time.