DEV Community: Son Do

Six Categories, Some Locked: Designing a Legal Chart of Accounts

Son Do — Sat, 25 Jul 2026 02:10:14 +0000

Series -- When the Aggregate Looks Right: 0: Overview · 1: Chart of Accounts · 2: Three-Way Reconciliation · 3: The Aggregate Can Lie · 4: Bank Sync · 5: GL Integration

The default assumption when building an accounting module for businesses is that they know their own books. A law firm that has been tracking its finances for ten years has account names, structures, and categories that work for its practice. The obvious product instinct is to give them full control: let them rename accounts, restructure categories, delete what they do not use.

That instinct is wrong, at least for the accounts that billing, invoicing, and compliance matching depend on.

What a legal chart of accounts looks like

The module pre-populated a chart of accounts at onboarding, organized into six top-level categories: Assets, Liabilities (with a segregated trust account under it), Equity, Revenue, Expenses, and Compensation. The legal-specific structure differs from a standard business chart mainly in the trust liability account, which holds client funds the firm has not yet earned, and in how compensation is tracked separately from operating expenses for partnership accounting reasons.

Each category came with system-defined sub-accounts appropriate to a law firm. Firms could add their own sub-accounts under any category. They could rename their own custom accounts freely. What they could not do was rename or delete the system accounts.

That restriction is what this post is about.

Why auto-posting breaks with a moving target

When a firm sends an invoice through MyCase billing, the accounting layer needs to post the corresponding journal entries automatically. An invoice creates an accounts receivable entry on the asset side and a revenue entry on the income side. A payment marks the receivable satisfied and records cash or, for trust-funded payments, moves money from the trust liability account to the operating side.

Every one of those postings needs to land in a specific, stable place in the ledger. The posting logic does not ask the firm which account to use. It knows, because the chart of accounts has a defined structure with fixed identity for system accounts.

If a firm could rename "Trust Account" to "Client Funds" or delete it and create an equivalent under a different structure, the billing integration would post to an account that no longer exists under the expected name. The transaction would fail, or worse, post to a default catch-all with no meaningful category.

The same problem applies to expense entry and to the invoice-exact matching in Part 3. Matching a trust-to-operating transfer against the invoice that authorized it requires finding both the trust transaction and the invoice's corresponding posted entry. If the account names or identities can shift, the lookup falls apart.

The customization boundary

Locking accounts does not mean firms get no flexibility. The system accounts define the roots and some first-level structure. Anything below that is fair game. A firm that tracks fees in several categories can add sub-accounts under Revenue. A firm with specialized expense categories can build those under Expenses. None of that custom structure touches the system accounts that auto-posting and compliance matching depend on.

The product framing for this was straightforward: the locked accounts are ones the system writes to on your behalf. Everything else is yours to organize how you see fit.

In practice, the most common request from early adopters was renaming the trust account to match whatever they had been calling it in their previous system. The answer was a sub-account alias, not a rename of the root. The root kept its identity; the firm could see whatever label they preferred in their own views.

The downstream dependency

It would be easy to treat the chart of accounts as plumbing: necessary, not interesting. But the lock decision has a direct effect on everything built on top of it.

The three-way reconciliation in Part 2 works because the firm trust ledger has a known structure. The matching logic in Part 3 works because a posted invoice has a stable account identity to match against. The bank sync in Part 4 can distinguish trust accounts from operating accounts because that distinction is encoded in the chart, not inferred from whatever the firm named their accounts. The GL integration in Part 5 can post billing and LawPay events at event time because the target accounts are always there.

Firms that wanted full customization got it in the places where customization does not break the system. Firms that wanted to rename or delete system accounts got an explanation of why that was not possible and what the alternative was. A few firms pushed back. The answer was always the same: these accounts are written to on your behalf, and that only works if they have a stable identity the system can find.

Series -- When the Aggregate Looks Right: 0: Overview · 1: Chart of Accounts · 2: Three-Way Reconciliation · 3: The Aggregate Can Lie · 4: Bank Sync · 5: GL Integration

Building MyCase Accounting: Trust Books That Can Look Right While Being Wrong

Son Do — Sat, 25 Jul 2026 02:10:09 +0000

Series -- When the Aggregate Looks Right: 0: Overview · 1: Chart of Accounts · 2: Three-Way Reconciliation · 3: The Aggregate Can Lie · 4: Bank Sync · 5: GL Integration

The call came in mid-morning. A firm had reconciled their trust account the day before. Bank balance matched the firm ledger to the cent. Books were closed for the month.

The client calling was asking about their retainer. The paralegal pulled up the matter. The trust sub-ledger for that client showed a balance several hundred dollars lower than the client expected. Funds meant for one matter had been drawn against another. No one had noticed because the aggregate absorbed the error. The bank only ever showed one pooled number.

That failure mode is not a bug in someone's arithmetic. It is what happens when you watch the wrong thing. A pooled IOLTA trust account hides client-level movement inside an aggregate that can reconcile cleanly while individual slices are wrong. The aggregate can lie.

The problem IOLTA creates

IOLTA stands for Interest on Lawyers' Trust Accounts. Most states require attorneys to hold unearned client funds in a pooled trust account rather than the firm's operating account. Retainers go in. Invoices draw against them. The interest goes to a state bar fund.

The pooled structure creates an accounting problem the bank cannot solve. The bank sees one account. The firm has obligations to dozens of clients, each with their own retainer and their own matter. State bar rules require firms to know, at any point, exactly how much of that pooled balance belongs to each client. A discrepancy is not an accounting quirk. It is a bar-complaint risk.

Banks report balances. They do not track sub-ledgers. The firm is responsible for maintaining the client-level view. In 2021, most firms using MyCase were doing that tracking manually, in spreadsheets or separate bookkeeping software, reconciling monthly or not at all.

That is the gap the module was built to close.

What the series covers

The module had five interlocking parts. Each one is a separate post in this series.

Part 1 -- The chart of accounts. Before any posting or matching could work, the module needed a stable ledger structure. Six top-level categories -- Assets, Liabilities (including segregated trust), Equity, Revenue, Expenses, Compensation -- pre-populated with legal-specific accounts. Some accounts were locked because billing, invoicing, and expense entry auto-posted to them. Firms could customize via sub-accounts but could not rename or delete the roots. The downstream safeguards in Part 3 depend on that stability.

Part 2 -- Three-way reconciliation. Bank statement versus firm trust ledger versus per-client trust sub-ledgers. Two-way matching (bank against firm books) will pass while a client-level slice is wrong, because the pooled bank account cannot see individual matters. The design decision that made three-way runnable at scale: auto-generating client trust sub-ledgers from existing MyCase client records instead of requiring firms to set up sub-ledgers manually. Firms that had to build the third leg themselves skipped it. Without the third leg, three-way is two-way with paperwork.

Part 3 -- Safeguards against flagging too much. Once you can see client-level balances, the next problem is catching errors without burying reviewers in noise. This is the post that was already published as "The Aggregate Can Lie." It covers naive flag-everything, the false-positive flood it produces, and the invoice-exact matching design that caught real violations without producing daily alert fatigue.

Part 4 -- Plaid bank sync. Pulling bank feeds via Plaid required a decision that is not obvious until you see the failure: trust accounts cannot follow the same categorization workflow as operating accounts. If the firm has already recorded a trust transaction in MyCase, importing the bank line and categorizing it into a GL account creates a second source of truth and breaks the three-way model. The For Review pipeline, and why trust transactions skip categorization entirely, is Part 4.

Part 5 -- GL integration. The last loop to close was eliminating re-keying. An invoice already lived in MyCase billing. A payment already hit LawPay. A bookkeeper was re-entering both into accounting. The integration posts billing and payment events directly to the GL at event time -- trust versus operating routing handled by the locked chart of accounts from Part 1 -- so there is nothing left to re-key and no lag between what billing recorded and what the books show.

What it shipped as

The module reached general availability after the AffiniPay acquisition closed in June 2022. Within twelve months of GA, 18% of eligible firms had enabled it.

For those firms, monthly trust reconciliation dropped from roughly six hours of manual work to under thirty minutes per cycle. The six hours was mostly matching -- pulling bank statements, cross-referencing firm records, hunting for discrepancies. The thirty minutes is reviewing a screen of pre-matched items and confirming the ones that need a human decision.

What comes first

Part 1 starts with the chart of accounts, because nothing else in the module works without it. The three-way reconciliation needs stable account identity to match against. The bank sync needs to know which accounts are trust and which are operating before it can route a feed line. The GL integration needs locked system accounts to post into.

A fully customizable chart looks like the right call when you are onboarding a firm that already has books. It turns out to be the wrong call the moment auto-posting and compliance matching need to find an account that has not been renamed or deleted. Part 1 is about that tradeoff.

Series -- When the Aggregate Looks Right: 0: Overview · 1: Chart of Accounts · 2: Three-Way Reconciliation · 3: The Aggregate Can Lie · 4: Bank Sync · 5: GL Integration

The Hardest Part Wasn't the Code: Aligning Stakeholders on Metric Definitions

Son Do — Thu, 23 Jul 2026 09:50:29 +0000

Series -- From Ad-Hoc SQL to a Semantic Layer: 0: Overview · 1: Ten Answers · 2: Why Not Indexes · 3: Metrics Model · 4: View Pipeline · 5: Schema Design · 6: Authorization · 7: Migration Sequence · 8: Stakeholder Alignment

A domain owner pulled me into a call in early 2024 with two reports open side
by side. Both claimed to show billable hours for the same firm over the same
period. The numbers were different, and the question was simple: which one is
right. I couldn't answer it. Nobody on the call could. Each report had its
own SQL, written by someone else at some other time, and each had quietly
decided for itself what "billable" meant.

I have opened this series with that scene once already, because it is the
moment the whole project became undeniable. But I want to come back to it
now, at the end, because the scene contains a trap. It looks like an
engineering problem, and the engineering answer is obvious: build one place
where "billable hours" is defined, and point every report at it. That is what
a semantic layer is. Seven posts of this series are about how we built it.

This post is about the part that the layer did not solve. Building one
definition does not settle a disagreement. It forces you to put exactly one
definition in the model, and the moment you do, every domain that had been
running a different implicit definition is now wrong by decree. The layer
does not end the argument. It makes the argument mandatory.

The easy conflict and the hard one

The billable-hours discrepancy had a root cause you could find. I sat down
with both queries and read them. One of them joined through invoices, so it
was counting only hours that had actually been invoiced. The other queried
time entries directly, so it counted every hour logged with a billable
status, invoiced or not. Same firm, same period, two honest numbers
answering two slightly different questions that both got called "billable
hours." Once you see the join, you understand the whole thing. The
disagreement was an accident of implementation, and the fix was to decide
which question we meant and write it down.

Trust balance was not like that. Under IOLTA, the rules governing how law
firms hold client money in trust, there were three definitions of "trust
balance" in play, and all three were correct. The bank statement definition
was the actual cash position, what the bank said was in the account right
now. The firm ledger definition was what the firm's own books showed it owed
across all clients. The per-client sub-ledger definition was what one
specific client had in trust at that moment. These are not three
implementations of one number. They are three different numbers that answer
three different questions, and a firm needs all three, for reconciliation,
for accounting, and for client-level compliance respectively.

There was no SQL to read that would resolve it. Nobody had made a mistake.
The disagreement was legitimate, and the only way through it was to decide
which question the analytics layer was going to answer, and to be explicit
that it was not answering the other two. That is not a debugging task. That
is a governance decision, and it needed someone with the authority to make
it and the willingness to be held to it.

Who decides what "billable" means

I drove the alignment across the four domains, but I was not the one who got
to decide what the metrics meant. The decisions belonged to the domain
product managers, one each for billing, trust, case, and financial. They
were the people who owned the consequences of getting a definition wrong,
and so they were the ones who had to own the definition.

What I built was the process that forced the decision to happen and made it
stick. Every contested metric got a written definition doc. The doc named
the competing definitions explicitly, laid out which report or which domain
had been using each one, and stated the canonical resolution: this is what
"billable hours" means in the semantic model, this is the question it
answers, and here is what it deliberately excludes. The relevant domain PM
signed off on the doc before the metric was committed to the model.

That sign-off was the whole point. Not a verbal agreement on a call, which
evaporates the moment someone's report shows a number they do not like. Not
an escalation to a VP, which turns a definition question into a political
one and teaches everyone to escalate next time. A written doc, with a named
decision, and a name on the approval. When a report later showed a number
someone disputed, the answer was not "let me check the query." The answer
was "here is the definition your domain signed off on, and here is the doc."
The disagreement had already been had. We were just looking up the result.

The weeks that were not engineering time

The honest cost of this shows up in the trust domain. The trust accounting
reports were built. The materialized views were ready, the GraphQL schema
could express them, the caching worked. The reports could have shipped. They
did not ship, for weeks, because the three-ledger trust balance question was
still live and nobody had signed a doc.

Those weeks were not engineering time. Nothing was being coded. The
infrastructure sat finished and waiting while the billing PM, the trust PM,
and the financial PM worked out which trust balance the platform would
report and how to scope the other two so the reports that genuinely needed
them could still get them. When people talk about how long a migration took,
they usually mean how long the code took. On this project, a real fraction
of the calendar was alignment time, and no amount of engineering velocity
would have shortened it, because the bottleneck was agreement, not
implementation.

I found that clarifying rather than frustrating, eventually. The reports were
blocked by exactly the thing they should have been blocked by. Shipping them
faster would have meant shipping them on a definition nobody had agreed to,
which is how you end up with two reports showing different billable-hours
numbers in the first place.

What never resolved

Not every definition got settled. Some metrics stayed domain-specific,
permanently. In the previous post I mentioned the 5 to 10 reports out of the
original 30-plus that never migrated onto the new platform. A subset of those
were not stuck on traffic or effort. They were stuck on definitions that
never got sign-off, because the domains could not agree and the use case was
too narrow to force the question to a conclusion.

Those reports stayed on their legacy queries indefinitely. Each one kept its
own private definition of whatever it measured, the same way all 30 reports
used to. From an engineering standpoint that is unfinished work. From a
different standpoint it is the most honest output of the project. You migrate
most of a thing like this, and the parts you cannot migrate tell you
something true about your organization's actual ability to agree on shared
meaning. Some questions did not have one right answer that four teams could
live with, and the platform was better for admitting that than for forcing a
false consensus into the model.

Every migration was a governance event

Here is the insight I did not have going in. Forcing reports onto shared
definitions was progress, and it was the entire point of the semantic layer.
But it also meant that every single report that migrated required a decision.
Someone had to say, officially and in writing, what "billable" or "active"
or "trust balance" meant for the platform, and then be accountable for that
decision when a number moved.

That is a fundamentally different kind of work than building infrastructure.
Materialized views and GraphQL schema evolution are hard in a way that yields
to engineering: you can think harder, test more, refactor. Getting four
teams to agree that they had been measuring the same thing differently, and
that the platform was going to pick one definition and hold it against
everyone's objections, does not yield to any of that. It yields to a written
doc, a named owner, and the patience to let the argument happen instead of
routing around it.

The day the domain owner checked two reports on the unified platform and the
billable-hours numbers matched, the project felt done to me, well before the
migration actually was. Not because the code was finished. Because the two
numbers were finally answering the same question, and there was a doc, with a
name on it, that said why.

Which Report Goes First: The Migration Sequencing Logic

Son Do — Thu, 23 Jul 2026 09:50:25 +0000

Series -- From Ad-Hoc SQL to a Semantic Layer: 0: Overview · 1: Ten Answers · 2: Why Not Indexes · 3: Metrics Model · 4: View Pipeline · 5: Schema Design · 6: Authorization · 7: Migration Sequence · 8: Stakeholder Alignment

The engineering problem was solved. The semantic model worked, the
materialized views were refreshing on schedule, and the authorization-aware
GraphQL API was live and returning correct results. I remember the specific
relief of watching a query come back through the new layer and matching it
by hand against the old read replica. The numbers agreed.

And then I looked at the list. Thirty-plus reports were still pointing at
the old read replica, none of them aware that a better path existed. The
migration problem was just starting, and it opened with a question that had
nothing to do with materialized views or schema design: in what order do you
move them?

Two axes, not one

It is tempting to sequence a migration by traffic alone. Move the heaviest
queries first, get the biggest latency win, declare progress. That instinct
is half right, and the missing half is what made this migration interesting.

There were two axes that mattered, and the Part 0 overview names both of
them: how load-bearing a report was, and how contested its metric
definitions were.

"Load-bearing" was not just query volume. It was a combination of replica
traffic and business consequence. A report that firms used to make billing
or collections decisions carried more weight than a case-summary report that
someone glanced at occasionally, even if the two had similar query counts. A
report could be low-traffic and still high-stakes, because the cost of it
being wrong was measured in a firm's money rather than in database load.
Load-bearing meant "how much breaks, and how badly, if this migration goes
wrong."

"Contested" was a different thing entirely. It measured whether the metric
definitions behind a report required stakeholder alignment before migration
was even technically possible. A report built on a disputed definition could
not move, because there was nothing for it to move onto. The semantic model
demanded exactly one canonical version of each metric, and until the
stakeholders agreed on what "trust balance" meant, the model had no version
of it to offer. Contested meant "how much agreement has to happen before the
new layer can accept this at all."

How the two axes interacted

Plot every report on those two axes and the sequence writes itself, mostly.

Low-load, low-contested reports went first. These were the proof-of-concept
migrations, the ones where the goal was not the latency win but the
demonstration: prove the pattern works, validate that the new layer returns
correct results, build confidence before touching anything that a firm would
notice. If something went wrong here, the blast radius was small.

High-load, low-contested reports were the compelling early wins. Once the
pattern was proven, these were where the latency numbers came from. Their
definitions were settled, so there was nothing blocking them, and their
traffic meant moving them mattered. This is the group that made the project
look successful to anyone watching the dashboards.

High-contested reports went last, and here is the part that traffic-first
sequencing gets wrong: they went last regardless of load. A high-traffic,
high-contested report could not jump the queue on the strength of its
traffic, because the semantic model physically could not accept it until its
definitions were settled. Contention was a hard gate, not a soft
preference. You can defer a low-priority migration; you cannot migrate a
report whose central metric has three competing definitions and no agreed
winner.

Starting with case analytics

The first domain we migrated was case analytics: active case count, case
status, and the reports built on them. On both axes, these scored lowest.

"Active case" is close to an enum-level concept. A case is open or it is
not, and while there are edge cases, they are the kind you can resolve by
reading a status column rather than by convening four teams. There were no
IOLTA implications, no invoicing dependencies, no money riding on the exact
boundary of the definition. And these reports were lower-traffic than the
billing reports that firms hit constantly.

That made case analytics the right proof-of-concept. We migrated these
reports first not because they were urgent but because they were safe. They
let us exercise the whole pipeline -- semantic model, materialized view,
GraphQL query, cache, frontend shell -- against real reports without
gambling on a definition that might still be under dispute. By the time we
moved to anything financial, the pattern had already survived contact with
production.

Why trust accounting was last

At the far corner of the grid sat trust accounting, and it stayed there
until the end.

Trust balance has three legitimate answers under IOLTA, the rules governing
how law firms hold client money. There is the bank statement figure, the
firm ledger figure, and the per-client sub-ledger figure, and each is
legally valid in a different reporting context. This is not a bug or a
disagreement to be resolved by picking the smartest engineer's preference.
All three are simultaneously correct, and choosing which one a given report
should show is a compliance decision, not a technical one.

No trust report could migrate until that question was resolved and the
domain PM signed off on a canonical definition, or on an explicit scoping of
which definition belonged to which report. So the trust reports sat in the
queue while the alignment work ran alongside the migration. That alignment
work is the subject of Part 8; for sequencing purposes, the relevant fact is
that trust was gated on a conversation, not on engineering effort, and the
conversation took time.

Parallel running and shadow comparison

Each report migrated one at a time, and each one went through a shadow
comparison period before cutover. The legacy query and the new layer ran
simultaneously, both producing output, and we compared the two before
decommissioning the legacy path. A migration was not "done" when the new
query returned results; it was done when the new query had agreed with the
old one across a validation window.

For billing and trust reports, that window was longer. When a report drives
a firm's collections decisions, or touches client trust money, the bar for
"we are confident these match" is higher than it is for a case-count report.
More confidence required a longer comparison period, which is another way
the load-bearing axis expressed itself: it did not just influence order, it
influenced how carefully each cutover happened.

What stayed behind

The honest version of "we migrated the system" is that we migrated most of
it. Twenty to twenty-five of the thirty-plus reports moved. The remaining
five to ten did not, and they fell into two groups.

The first group was low-traffic, edge-case reports: one-firm customizations,
rarely-accessed summaries, reports where the cost of migration plainly
exceeded the benefit. Nobody was going to reap a latency win on a report run
twice a quarter, and rebuilding it on the new layer was effort spent for
almost no return.

The second group was blocked on metric definitions that were never fully
resolved. Some disagreements did not converge. Where a definition fight
stalled and the report was not important enough to force the issue, the
report stayed on the legacy query path permanently. Those reports are still
there, as far as I know, quietly running their own SQL against the replica,
each with its own private answer.

Every migrated report was a governance artifact

Here is what the sequencing revealed that the design work had obscured.
Every report that successfully migrated was also proof that a definition had
been agreed on. You could not move a report onto the semantic model without
first settling what its metrics meant, so a migrated report was a
governance artifact as much as an engineering one.

The write-off case from Part 0 makes this concrete. A write-off was excluded
from one billing report and included in another, and that was not a bug. It
was a definition that had never been made explicit, and migration forced it
into the open. Someone had to decide, on the record, which treatment was
correct, and that decision became part of the model.

This is why sequencing was not a purely mechanical exercise. The order in
which reports migrated determined which definitions got forced into the open
in which order, and that in turn determined which stakeholder conversations
were live at any given moment. Migrating the billing reports meant the
write-off conversation had to happen then; deferring trust meant the IOLTA
conversation could wait. The migration schedule was, in effect, a schedule
for the arguments.

That is also why the sequencing decisions were made jointly with the program
PM, not purely by engineering. Which reports moved first was not only a
technical call. The PM had visibility I did not into which firm-facing
reports were politically sensitive or tied to external stakeholder
commitments, and that visibility fed directly into the order. Co-owning the
sequence with someone who understood the business stakes was not a courtesy.
It was the only way to sequence a migration whose real constraint was
agreement rather than code.

Authorization at the API Layer: Why Field-Level Checks Live in GraphQL

Son Do — Thu, 23 Jul 2026 09:50:21 +0000

Series -- From Ad-Hoc SQL to a Semantic Layer: 0: Overview · 1: Ten Answers · 2: Why Not Indexes · 3: Metrics Model · 4: View Pipeline · 5: Schema Design · 6: Authorization · 7: Migration Sequence · 8: Stakeholder Alignment

Part 1 of this series described a call where two reports claimed to show
billable hours for the same firm over the same period and disagreed, because
each report had quietly decided for itself what "billable" meant. There was a
second version of that same problem that nobody put on a call, because it
never surfaced as a visible contradiction. It surfaced as a compliance
question instead.

Each of the 30-plus legacy reports was also hand-rolling its own permission
checks against raw tables. One report decided for itself whether the person
running it was allowed to see a firm's trust balance. Another report, pulling
from the same underlying data, made its own separate decision. Thirty reports
meant 30 different answers to "who can see this data," scattered across 30
different SQL queries, with no single place that said what the rule actually
was. For a legal SaaS handling trust accounting and payment data, that
fragmentation was not just a maintenance burden. It was a compliance surface.
Every one of those 30 decisions was a place where the rule could be wrong, and
no way to audit whether it was.

When I designed the unified analytics platform, authorization was not a
feature I added to the GraphQL API after the fact. It was the constraint that
decided where the API layer had to sit at all.

Three places the check could live

There were three honest candidates for where authorization could be enforced,
and picking the wrong one was easy to do because two of the three look
reasonable until you push on them.

The first was the controller layer: Rails, before the GraphQL resolver ever
runs. This is the instinct most Rails engineers reach for first, because
that is where authorization usually lives. The problem is that it does not
actually centralize anything. Each report route still has to know which
fields it is about to expose and gate each one. You have moved the check
upstream of the query, but you still need a check per route per field. Thirty
reports still means thirty places that each have to remember the rule. I would
have rebuilt the exact fragmentation I was trying to eliminate, just one layer
higher up the stack.

The second was the view layer: the shared React report framework deciding
what to render. A report component could check whether the current user holds
view_trust_accounting and simply not draw the trust balance column if they
do not. This looks clean, and for a lot of applications it would be fine. It
was not fine here, and the reason is the distinction that ends up being the
whole point of this post: by the time the React framework decides not to
render a field, the data has already been fetched. The GraphQL query ran, the
resolver returned the trust balance, it traveled over the wire, and it is
sitting in the browser's memory. The UI is choosing not to paint it. For
IOLTA-governed trust data and PCI-relevant payment fields, withholding the
field in the UI is not the same thing as withholding the data. The data left
the server. That is the event that matters, and the view layer happens after
it.

That leaves the API layer: the GraphQL field itself. This is the only boundary
in the entire stack where declining to include a field in the response is the
same act as declining to send the data. If the resolver does not return the
trust balance, the trust balance does not enter the query result, does not
cross the network, and never reaches a browser that could be inspected. There
is no gap between "the user cannot see this" and "the data did not move."

That property is what settled it. Not convenience, not consolidation for its
own sake. The GraphQL field is the only place where "who can see this field"
and "does this data leave the server" are the same decision.

Two layers that compose without merging

The implementation splits authorization into two boundaries that stack rather
than blend into each other.

The first boundary is firm isolation, and it lives in the query scope layer. A
shared BaseResolver sits under every resolver in the schema, and before any
field logic runs, it scopes the query to current_firm. MyCase is
multi-tenant with law firms as the tenant, so this is the foundational rule:
no query, from any report, ever returns data belonging to a firm other than
the one making the request. Because it lives in the base resolver rather than
in individual resolvers, there is no report and no field that can opt out of
it, forget it, or get it subtly wrong. Firm isolation is not something a
resolver remembers to do. It is the ground every resolver stands on.

The second boundary is field-level access, and it lives in per-type Pundit
policy objects. A trust analytics type has a policy that checks the
view_trust_accounting permission. A financial analytics type has its own
policy, with stricter rules on the PCI-relevant fields, because payment data
carries obligations that a case-count metric does not. The BaseResolver
invokes the appropriate Pundit policy for each type. The authorization logic
lives in the policy object, not inline in the resolver, which means the rule
for a given type is written in exactly one file and read from exactly one
place.

These two boundaries compose without merging. Firm isolation runs first, at
the query scope, and establishes the tenant. Then, inside that already-scoped
query, the field-level Pundit policies run. A user has to clear firm context
before any field-level check is even asked, and clearing firm context tells
you nothing about whether they can see trust balances. The BaseResolver
guarantees the first; the policies guarantee the second. Keeping them separate
is deliberate: firm isolation is a tenancy invariant that must never have an
exception, while field-level access is a permission model that legitimately
varies by field and by domain. Collapsing them into one check would have
meant re-deriving the tenancy invariant every time I touched a field rule.

Why IOLTA and PCI drove the design

It would be easy to present field-level authorization as a nice-to-have that
happened to also satisfy compliance. That reverses the actual causality.
Compliance is why the model looks the way it does.

IOLTA governs how law firms hold client trust funds, and access to trust
account data has to be controlled in a way that can be audited. PCI compliance
for payment-adjacent fields carries a parallel requirement: you have to be
able to demonstrate that cardholder-adjacent data is gated at the data layer,
not merely hidden in the interface. Both of these are questions an auditor can
ask, and both of them demand a specific kind of answer. Not "we filter it in
the UI." Not "each report handles it." The answer that satisfies the question
is "this field is protected by this Pundit policy, and here is the policy
definition."

That answer is only possible because the checks are consolidated. Thirty
reports each making their own access decision against raw tables cannot
produce an audit trail, because there is no single artifact to point at. The
field-level model gives both IOLTA and PCI a concrete, inspectable boundary: a
named policy object, attached to a named type, checking a named permission.
The compliance story is a byproduct of putting the rule in one place, and
putting the rule in one place was only worth doing at the layer where the rule
also controls the data.

The payoff for every report that came after

The operational return showed up in reports I never touched. As described in
Part 5, new reports get composed from an L7 report-definition config rather
than written as fresh SQL. Because authorization lives in the schema and the
policy layer, a new report defined through that config inherits the entire
authorization model automatically. Firm isolation, trust-accounting gating,
payment-field rules: all of it is already there, underneath the field the new
report is consuming.

The important part is what a report author cannot do. They cannot forget to
add a permission check, because the check was never theirs to add. It is not
in the report config at all. It lives one layer down, in the schema, attached
to the type. A new report is a new arrangement of fields that are already
governed. There is no path through the config where a report author writes an
access rule, which means there is no path where they write it wrong.

This is the difference between "authorization-aware" as an adjective bolted
onto a finished GraphQL API and authorization-aware as a property the schema
was designed to have from the start. I did not build the analytics API and
then add access control. I put field-level access in the schema as a
first-class constraint, and that constraint is what made it safe to open the
same API to four separate report domains without each one auditing its own
access logic. The reports did not have to be trusted to enforce the rules.
The layer they query does it for them, once, in the only place where getting
it right and keeping the data on the server are the same thing.

Schema Without Churn: GraphQL Design for an Evolving Metrics Model

Son Do — Thu, 23 Jul 2026 09:50:18 +0000

Series -- From Ad-Hoc SQL to a Semantic Layer: 0: Overview · 1: Ten Answers · 2: Why Not Indexes · 3: Metrics Model · 4: View Pipeline · 5: Schema Design · 6: Authorization · 7: Migration Sequence · 8: Stakeholder Alignment

"Semantic layer" sounds like a foundation. Something you pour once, let cure, and build on top of with confidence that it will not move. That framing is exactly backwards for the state we were actually in. During the migration, the semantic model was the least stable thing in the system. Domain owners were seeing, for the first time, what "billable hours" had meant across four different report histories, and they were renegotiating the definition in real time. A write-off excluded from one billing report but counted in another was not a bug to fix; it was a decision nobody had ever been forced to make out loud.

So the GraphQL schema had a genuinely awkward job. It was the authoritative interface that live, in-production reports queried against, and it sat on top of a model whose definitions were still being finalized underneath it. A schema designed the obvious way would have needed a type change every time a metric definition shifted, and every one of those changes risked breaking a report that was already serving law firms. The whole post is about how we shaped the schema so those changes had somewhere to go that was not "break the consumers."

What the schema's boundary is for

In the stack, GraphQL is L3. It sits between the materialized views at L2 (covered in Part 4) and the React report framework at L4. The rule that made everything else tractable is a single sentence: reports query the schema, and reports never write SQL against the materialized views directly.

That boundary is the entire point of having an API layer at all. If reports could reach the views, then authorization, versioning, and consistency would each have to be re-solved by every report author, which is the exact failure mode the project existed to kill. Putting one access surface in front of the model means those three concerns live in one place. When the definition of a metric moves, it moves behind the schema. When a firm's permissions decide what a report can see, that decision is enforced at the schema. The report on the other side of the boundary does not know or care that anything underneath it changed.

The type hierarchy: domain-scoped roots, metrics-specific types

The first real design decision was the shape of the type hierarchy, and I landed on a hybrid. The query roots are domain-scoped, and each one returns a metrics-specific type. The required context lives as arguments on the domain root field, not nested somewhere inside.

type Query {
  billingAnalytics(firmId: ID!, dateRange: DateRangeInput!): BillingAnalytics
  trustAnalytics(firmId: ID!, dateRange: DateRangeInput!): TrustAnalytics
  caseAnalytics(firmId: ID!, dateRange: DateRangeInput!): CaseAnalytics
  financialAnalytics(firmId: ID!, dateRange: DateRangeInput!): FinancialAnalytics
}

type BillingAnalytics {
  billableHours: Float
  invoicedHours: Float
  writeOffAmount: Float
}

A billing report queries billingAnalytics. It does not query cases or timeEntries. That is deliberate: the domain objects that the transactional side of the product is built from do not leak into the reporting layer at all. The reporting layer sees metrics, grouped by domain, and nothing else.

Why this hierarchy and not the other two

Two alternatives were on the table, and rejecting them is what makes the hybrid a decision rather than a default.

The first was to make domain objects the query root and hang metrics off them through entity relationships, so a billing report would traverse something like cases { billingMetrics }. That reads naturally right up until you notice what it does to coupling. It ties the reporting layer to the structure of the domain model. Every report would have to know how to compose through the entity graph to reach a number, and any refactor of how cases relate to matters or invoices would ripple straight into report queries. The reporting layer has no business knowing the domain model's join topology. Separate metrics types sever that dependency: a metric is a field on an analytics type, full stop, and how it is computed underneath is invisible.

The second question was where the context arguments go. Putting firmId and dateRange on the root domain field, rather than nesting them on individual metric fields, means the firm context and the reporting window are always required and always explicit. There is no way to ask for billableHours without having already declared which firm and which date range you mean. In a multi-tenant legal SaaS that is not a convenience; it is the property that keeps firm A's numbers from ever being computable in a query that was scoped to firm B.

The anti-churn rule: additive-only, deprecate, then remove

The type hierarchy solved coupling. It did not, on its own, solve the moving-model problem. That took a rule about how the schema is allowed to change while reports are live on it, and the rule is additive-only.

A new metric is a new field on the relevant analytics type. Existing fields are never removed and never renamed while any report is still reading them. When a metric genuinely needs to go away or change meaning, the old field gets GraphQL's @deprecated directive with a reason, and it stays in the schema, still resolving, until every consumer has moved off it. Only then does it get removed.

type BillingAnalytics {
  billableHours: Float
  invoicedHours: Float
  writeOffAmount: Float

  "Use billableHours; this excluded write-offs inconsistently across firms."
  billableHoursLegacy: Float @deprecated(reason: "Superseded by billableHours as of the unified write-off definition. Remove after all reports cut over.")
}

This is the same lifecycle the metric classes use underneath. Where the Ruby side keeps a VERSION and lets an old and new definition of a metric coexist so history is not silently rewritten, the schema keeps the old field and the new field coexisting so no live report reads a definition that moved out from under it. It is one pattern applied at two layers: a definition change is always a coexistence period, never a hard cutover. When a domain owner renegotiated what "billable" meant, that change landed as a new field with a new definition, the old field went deprecated, and the reports that depended on the old meaning kept working until they were deliberately migrated. Nothing broke on the day the definition changed, which is the only way a moving model and live consumers can share a schema at all.

The payoff at L7: reports as config, not SQL

All of this pointed at one concrete result, and it lives at L7, the report-definition config layer. Because the schema is a stable, composable surface of metrics grouped by domain, a new report is not a new query written against production. It is a config entry that selects fields from one or more analytics types.

That is the mechanism behind the number I care about most from this project: new-report delivery going from two to three weeks down to about four days. A new report required no schema change and no new SQL. It composed fields that already existed on types that already existed, through the same authorized access surface every other report used. The engineer who built the first report on the new platform never wrote a line of SQL against production, and the reason they did not have to is that the schema had been designed so that composing a report was a config problem, not a query-authoring problem.

The insight I would carry to the next system is that the schema was designed for evolution, not for stability. Those are not the same goal, and confusing them is how you end up with a schema that is either brittle or frozen. Designing for evolution meant treating the anti-churn rules as load-bearing constraints from the first line of SDL, not as a governance policy bolted on after the schema was already in production. Additive-only, deprecate-then-remove, context on the root, metrics as fields: those were not conventions we adopted once churn became painful. They were the assumptions the schema was built on, precisely because we knew going in that the model underneath it was going to move.

Part 6 goes into the authorization model that this access surface made possible: why field-level, firm-scoped checks belong at the GraphQL layer and nowhere else.

Never Miss a Refresh: Building the Materialized View Pipeline

Son Do — Thu, 23 Jul 2026 09:50:14 +0000

Series -- From Ad-Hoc SQL to a Semantic Layer: 0: Overview · 1: Ten Answers · 2: Why Not Indexes · 3: Metrics Model · 4: View Pipeline · 5: Schema Design · 6: Authorization · 7: Migration Sequence · 8: Stakeholder Alignment

The metrics model from the last post gave us one place to define what a business word means. Materialized views gave us a fast place to read it from. But a materialized view is a photograph, not a mirror. It shows the data as it was the last time something took the picture, and the whole speed advantage of the semantic layer rested on a fact that was easy to underestimate: those pictures only stay useful if something keeps retaking them.

I want to invert the Part 0 framing here, because the inversion is the point. The interesting problem was not how to invalidate the cache. It was how to design the refresh pipeline so that cache invalidation stopped being a separate problem at all. Once I saw that the refresh schedule and the cache freshness were the same question wearing two hats, most of the design fell out on its own. Getting there meant being honest about the failure modes of the word "schedule," which sounds solved right up until you ask what happens on the run that doesn't finish.

The refresh pipeline

The scheduler was Sidekiq-Cron, chosen for the least glamorous reason available: Sidekiq was already in the stack. We had workers, a Redis instance behind them, retry semantics, and a web UI that on-call already knew how to read. A dedicated scheduling process, or pg_cron inside the database, would have meant a new operational surface to solve a problem the existing one already covered.

The job itself was deliberately dumb. A single ViewRefreshJob iterated every registered Analytics::Metrics subclass and, for each one, ran REFRESH MATERIALIZED VIEW CONCURRENTLY against that metric's backing view. Because the metrics model already knew every view name (that was the whole point of the registry from Part 3), the refresh job did not maintain its own list of what to refresh. It asked the model, so a newly added metric showed up in the next refresh cycle for free.

The CONCURRENTLY flag was not decoration. A plain REFRESH MATERIALIZED VIEW takes an exclusive lock for the duration of the rebuild, so every report reading that view blocks until the refresh finishes. For a reporting layer that firms hit during business hours, that is a self-inflicted outage on a timer. CONCURRENTLY rebuilds the view alongside the old one and swaps it in, so reads keep hitting the last good copy the entire time. It costs more and requires a unique index on the view, but it buys the one property this layer could not live without: the refresh is invisible to the person reading a report.

Every run also logged its per-view duration to Datadog, which is what the monitoring later hung off of.

Why the background was the right place for the cost

The trade the whole architecture made was to move expense off the read path and onto the refresh path. A report reading from a materialized view answered in single-digit milliseconds, because it was reading a purpose-built table, not reconstructing an answer out of the OLTP schema on every request. The bespoke queries these views replaced took seconds, and they took those seconds while a user waited. Rebuilding a view is not free, but that cost landed in a background worker with nobody watching a spinner. The reports felt instant because the slow part had already happened.

What happens when a refresh fails

Here is the question that separates a schedule from a pipeline: what does the system do on the run that does not finish. A worker gets OOM-killed, a rebuild deadlocks, the database is briefly unreachable. The refresh fails. Then what.

The behavior we designed for, and got, was stale-and-silent. Postgres does not blank out a materialized view when a refresh fails; it keeps the last successful state. So a failed ViewRefreshJob left the view exactly as it was after the previous good refresh. The job failed loudly in Sidekiq, where the failure belonged, but no exception reached the report consumer. The report kept returning the last good data as if nothing had happened.

For this domain, that was the correct failure mode, on purpose. The consumers were billing reports, trust accounting, financial summaries. If a refresh fails at 6am, a firm looking at yesterday's numbers a few minutes into the delay is seeing data that is slightly stale but internally consistent and still trustworthy. Handing that same firm a stack trace where a number should be is strictly worse. Stale data a person can reason about beats an error a person cannot, so the pipeline was built to degrade toward the last known good answer rather than a visible break.

Silent staleness is only safe if it is not actually silent to the people running the system, and that is what the monitoring was for. Two signals, not one. The first was obvious: a Datadog alert on ViewRefreshJob failure, so a failed run paged someone. The second was subtler and more important. We tracked view age directly and alerted if any view had not refreshed within its expected cadence. That caught the failure modes the first one missed: the runs that never threw an exception because they never started, and the ones that hung past the window without technically failing. A job that fails is easy to see. A job that quietly stops running is the one that lets data rot, and the view-age check was the trap for exactly that.

The cache invalidation insight

Everything above sets up the decision I am most attached to on this project, because it is where two problems collapsed into one.

Sitting in front of the views was Redis, and the question was how a cached report answer knew when to stop trusting itself. I looked hard at two standard approaches and turned both down, for reasons that only become visible once you understand how the views actually refresh.

A fixed TTL, cache each answer for N minutes and then evict, has a blind spot that is structural, not tunable. A TTL knows how long it has been since the answer was cached. It knows nothing about when the underlying view last refreshed. Those are different clocks. A freshly refreshed view and a badly stale one, cached at the same moment, expire at the same moment, because the TTL cannot tell them apart. To guarantee freshness you would have to set the TTL short enough to chase the fastest possible refresh, throwing away most of the caching benefit to wait on a timer with no relationship to when the data actually changed.

Event-driven invalidation, bust the specific keys the instant the underlying data changes, is more precise on paper and was a worse fit in practice. Being precise about "when the data changes" means hooking every write path that could change it, across case, billing, trust, and financial domains. That is an N-domain coordination problem, and one missed write path means a report serving stale data with no signal that anything is wrong. It was at its most dangerous during the migration, exactly the window this whole series lives inside, because some legacy reports were still writing directly against the same tables the new model was reading. The domain boundaries were the least stable they would ever be, and this approach demanded I coordinate across all of them at precisely that moment. It was the right tool aimed at the wrong week.

So I keyed the cache to each view's own refresh timestamp instead. The cache key for a report answer included the refresh time of the view it was computed from, and the mechanism that follows is almost too simple to feel like a decision. When a view refreshes, its timestamp changes, so every key derived from it changes, so the next read is a cache miss that recomputes against fresh data. When a view does not refresh, whether on schedule or because a run failed, its timestamp does not move, the key stays valid, and the cache keeps serving the last good answer. A stale view produces a stale key produces a miss, with no invalidation code anywhere in the system. Freshness stopped being a second system I had to keep in sync with the refresh pipeline and became a side effect of the pipeline itself. Updating the data is what invalidates the cache, because the data's own freshness marker is baked into the key. The problem was never how to invalidate the cache; it was how to design the refresh so that invalidation was something the refresh already did.

On the hot paths, the billing and case reports that firms hit on essentially every login, this landed at a 65% cache hit rate. Those are the queries where the same handful of views get read over and over between refreshes, which is exactly the shape timestamp keying rewards: a stable key between refreshes means repeated hits, and the one guaranteed miss per refresh is the miss you want.

The shape of the whole thing

What I keep coming back to is that the failure behavior was layered on purpose. A failure in the refresh pipeline degrades gracefully: the view holds its last good state, the timestamp-keyed cache keeps serving from it, the view-age check catches the staleness before a user does, and the reader never sees an error in a report a firm is using to move client money.

None of the individual pieces here are exotic: Sidekiq, REFRESH MATERIALIZED VIEW CONCURRENTLY, a Redis key with a timestamp in it. The design was in how they compose. Put the expense in the background, let failure fall toward stale rather than broken, and derive the cache key from the same freshness signal the refresh already produces, and the pieces stop being three systems that have to agree with each other and become one system that only has to be right once.

One Definition, 30 Reports: How We Designed the Metrics Model

Son Do — Thu, 23 Jul 2026 09:50:10 +0000

Series -- From Ad-Hoc SQL to a Semantic Layer: 0: Overview · 1: Ten Answers · 2: Why Not Indexes · 3: Metrics Model · 4: View Pipeline · 5: Schema Design · 6: Authorization · 7: Migration Sequence · 8: Stakeholder Alignment

The overview post ended on a governance insight: ten reports meant ten definitions of "billable hours," and fixing that meant someone had to arbitrate the disagreements. That is true, but it is only half the story. An agreement that lives in a meeting recording or a Confluence page decays the moment the next engineer writes the next report and quietly encodes their own interpretation again. The arbitration only sticks if it is embedded in something the code physically cannot route around.

So the design question for this post is narrower than "how do we align stakeholders." It is: once you decide to fix ten reports and ten definitions, what does "one definition" actually look like as software? What is the artifact you build that makes the agreement load-bearing instead of aspirational?

What a metric definition has to contain

The naive answer is that a metric is a SQL query. Define the query once, point every report at it, done. That is not wrong, but it undersells what the definition needs to carry to survive in a real codebase across a multi-month migration.

A query alone has no name that a human reading Ruby can reason about. It has no version, which matters enormously the moment you need an old definition and a new definition to coexist while reports migrate one at a time. And it has no place to record the business meaning in plain language, which is the single most valuable thing a metric definition can carry, because the whole reason the old world produced ten answers was that the meaning lived in nobody's head consistently.

So a metric definition, as we built it, had to contain four things. A name, so the definition is a first-class thing code refers to rather than an anonymous string of SQL. A version, so migration can happen incrementally without a flag-day cutover. A description, the business meaning stated in a sentence a domain owner could read and confirm. And a query, expressed not as raw SQL but as something reports could compose against rather than copy.

The class shape

Here is what that turned into. Every named metric became a Ruby class in an Analytics::Metrics namespace inside the Rails application:

module Analytics
  module Metrics
    class BillableHours < Base
      VERSION = 2
      DESCRIPTION = "Billable-status time entries, write-offs excluded"

      def self.view_name = :analytics_billable_hours_v2

      def self.query
        TimeEntry.joins(:matter).where(billable: true, written_off: false)
      end
    end
  end
end

The query method returns an ActiveRecord scope, not a string. That choice matters more than it looks. A scope is composable: a report that needs billable hours for a single firm over a date range starts from BillableHours.query and adds its own where clauses on top, rather than pasting the join-and-filter logic into yet another bespoke query. The definition of what "billable" means lives in exactly one method, and everything downstream builds from there. Reports call the metric class. Reports never write the billable: true, written_off: false predicate themselves, because the entire point is that they no longer get to decide what that predicate is.

The view_name is where the definition meets the physical database. The materialized views that the overview post described are not hand-written SQL files maintained separately from these classes. They are generated from the class definitions. analytics_billable_hours_v2 exists because BillableHours at VERSION = 2 declares it. The class is the source of truth, and the Postgres view is a materialized projection of what the class says. This is the mechanism that makes the canonical definition genuinely canonical: there is no second place where the meaning of billable hours could drift, because the view cannot exist without the class that defines it.

Versioning as a migration tool

The VERSION = 2 on that class is not decoration. It is what let this whole thing migrate incrementally instead of as a rewrite.

When a metric definition changed, we did not edit the existing class in place and break every report reading from it. We wrote a new class at a new version, which generated a new view, and left the old class and its view running untouched. Reports migrated off the old version onto the new one at their own pace, one at a time, and the old definition kept serving its remaining consumers correctly the entire time. When the last report reading v1 finally moved to v2, we dropped the v1 class and its view.

The cost of this is honest: view accumulation. For a while you have two materialized views representing two versions of the same metric, both refreshing, both taking up space, and you are carrying that duplication until the last laggard report cuts over. We accepted that cost deliberately. The alternative was coordinating a synchronized cutover of every report that touched a metric, at the same moment, which is exactly the kind of flag-day migration that turns a multi-month project into a single terrifying deploy. Coexistence bought us the ability to be incremental, and being incremental was the only way a team our size was going to migrate 20-plus reports without stopping the world.

Where the model got hard

If every metric had been as clean as billable hours, this would be a tidy engineering story and not much else. The hard ones were the metrics where more than one definition was legitimately correct.

Trust balance was the sharpest example. A law firm holds client money in trust, and "how much is in trust" has at least three legally meaningful answers. There is the bank statement balance, the actual cash sitting in the trust account. There is the firm ledger balance, what the firm's own books say is owed to clients in aggregate. And there is the per-client sub-ledger balance, what a specific client has in trust right now. Under IOLTA rules governing client trust accounting, all three are real, all three get reported in different contexts, and they can legitimately differ from one another at any given moment because of timing, uncleared transactions, and reconciliation lag.

This was not a case where one definition was right and the others were sloppy. It was a compliance-stakes alignment problem that no amount of reading the code could resolve, because the code was not where the answer lived. Getting to a single canonical TrustBalance metric, or deciding we actually needed three distinct named metrics, required pulling in the people who owned the compliance obligation and having them state which balance a given report was legally supposed to show. The class shape did not solve that. What the class shape did was give the resolution a permanent home: once the stakeholders agreed, the agreement became a DESCRIPTION string and a query method that could not be quietly reinterpreted later.

The model evolved as reality forced it to

The metrics model was not designed once, up front, and then frozen. It grew as the migration surfaced definitions nobody had ever written down.

The write-off case from the overview is the cleanest illustration. Write-offs were excluded from billable hours in one billing report and included in another. Neither was a bug. They were two undocumented decisions, made by different people at different times, that had coexisted for years precisely because there was no single place where the treatment of write-offs had to be stated. Migration forced the question into the open. You cannot write where(written_off: false) in a shared BillableHours.query without someone confirming that write-offs are, in fact, excluded, and confirming it as a decision that now applies everywhere.

That reframed what a migration actually was. Moving a report onto the semantic layer was never just a technical port. Each one was a governance artifact, proof that a definition had been explicitly agreed on, written into a class, and made binding on every future report that touched the same metric. The model got more complete with every report we moved, not because we planned each addition, but because each report dragged one more buried assumption into the light.

The payoff in the shape

The reason all of this was worth building as a class hierarchy rather than a folder of SQL files shows up in what the Base class bought us for free.

Because every metric is a subclass of Base, every metric automatically participates in the machinery around it without any per-metric wiring. The refresh pipeline that keeps the materialized views current, which is the subject of the next post, iterates over the registered subclasses and refreshes each one's view. Nobody adds a metric to a refresh schedule by hand. The GraphQL schema that reports actually query, which is the post after that, is generated from the same registry. A new metric becomes a queryable field the moment its class exists.

That is the quiet win of putting the definition in a class. You are not just recording what "billable hours" means in one place. You are making every metric a citizen of a system that already knows how to refresh it, expose it, and authorize access to it, so that adding the thirty-first metric costs almost nothing beyond agreeing on what it means. And agreeing on what it means, as the trust-balance story showed, was always the expensive part.

Why We Didn't Just Add More Indexes: Choosing a Semantic Layer

Son Do — Thu, 23 Jul 2026 09:50:07 +0000

Series -- From Ad-Hoc SQL to a Semantic Layer: 0: Overview · 1: Ten Answers · 2: Why Not Indexes · 3: Metrics Model · 4: View Pipeline · 5: Schema Design · 6: Authorization · 7: Migration Sequence · 8: Stakeholder Alignment

The first thing we tried was the obvious thing. We took the worst-offending
report queries, looked at their execution plans, and added indexes. We tuned
them one at a time, the way you would tune any slow query against a
production replica. It worked. For about two weeks the reports were fast
again and the load on the replica settled down, and it felt like we had
handled it.

Then the next report landed, and the same latency and load problems came
back. That was the tell. When a fix buys you two weeks and then the problem
returns wearing slightly different clothes, you are not looking at a
performance problem. As I covered in Part 1,
what actually broke at MyCase was that thirty-plus reports had each quietly
decided for themselves what "billable hours" meant, and no two of them agreed.
Index tuning treats the symptom of a query we would re-derive again next time.
It does nothing about the fact that the same definitions kept getting
re-derived at all. You cannot index your way out of a governance problem.

So we stopped tuning queries and started asking a harder question: what is
the right level of abstraction to put underneath thirty reports so that
"billable hours" gets defined once. That question had several plausible
answers, and most of this post is about the ones we ruled out, because the
reasons we ruled them out are what pointed us at the semantic layer.

The BI tool that solved the wrong three problems

The most tempting off-ramp was a business-intelligence tool. Something in the
Metabase or Looker family, where analysts build reports against a modeled
data source and you never write raw SQL for a report again. On paper it
addresses exactly what we were complaining about.

We evaluated one and rejected it on three blockers that all applied at the
same time. First, it could not embed natively in the MyCase product UI. These
reports are a product feature that law firms use inside the application, not
an internal dashboard for our own analysts, and a bolted-on iframe to a
separate BI product is not that. Second, it could not enforce firm-scoped,
field-level authorization. MyCase is a multi-tenant legal SaaS, and a trust
accounting figure that firm A can see is a figure firm B must never see, down
to the individual field. General-purpose BI tools are not built to enforce
that kind of per-tenant, per-field rule as a hard invariant. Third, it could
not express our business logic. What counts as billable, how a write-off is
categorized, how trust balances reconcile across three ledgers: that is domain
logic, and encoding it inside a BI tool's modeling layer would have just
moved the thirty-definitions problem into a tool that was worse at owning it
than our own codebase was.

Any one of those might have been workable on its own. All three at once meant
the BI tool was solving a problem we did not have while failing at the three
we did.

The data warehouse that was a later step, not an alternative

The other reflexive answer was a data warehouse. Move the analytics workload
off the transactional replica entirely, into a system built for it. I want to
be precise here, because a warehouse is a genuinely good idea and we did not
reject it on its merits. We rejected it as an answer to this problem.

A warehouse moves data. It does not decide what the data means. If you take
thirty ad-hoc queries and point them at a warehouse, you have thirty ad-hoc
warehouse queries, and each one still gets to invent its own definition of
billable hours on the way through. The consistency problem survives the move
completely intact, now with a bigger bill attached. The semantic layer is the
prerequisite, not the alternative. Once the definitions are canonical and live
in one place, a warehouse can absolutely sit underneath as a performance and
scale decision. But it has to sit under the definitions, not instead of them.

That reframing mattered for sequencing too. Treating the warehouse as a future
step meant we did not block the fix that actually addressed trust erosion on a
much larger infrastructure migration.

The faster database that would have preserved the problem

The last one is the subtlest, and it is the one I have to talk teams out of
most often. If reports are slow and hammering the replica, why not just make
the reads faster: a beefier database, or a caching proxy in front of the
existing queries.

Both of those preserve the actual problem exactly. The meaning of the data
would still live in thirty different places. You would have made thirty
inconsistent answers arrive more quickly. A cache in front of divergent
queries caches divergent results. Part 0 documents this reasoning directly,
and it is the load-bearing insight of the whole project: performance tooling
downstream of competing definitions locks in the mess instead of clearing it.
The fix had to move the definition upstream, and no amount of read throughput
does that.

Why the semantic layer, and why not just materialized views

Here is the distinction that took me the longest to articulate to
stakeholders, because materialized views were part of the eventual design and
it is easy to conflate the two.

The materialized views are a performance optimization. They pre-compute the
shape of the data so a report is not reverse-engineering it out of OLTP tables
on every request. What they do not do is decide what "billable" means. A
report querying a view directly still has to make that decision at query time,
which means we would be right back to thirty query authors making thirty local
choices, just against a faster source.

The semantic layer is what moves that decision upstream and locks it down. In
our case that layer was a Ruby module namespace, one class per named metric,
with the canonical definition living in the class and versioned by convention.

module Analytics
  module Metrics
    class BillableHours < Base
      VERSION = 2
      DESCRIPTION = "Billable-status time entries, write-offs excluded"
      def self.view_name = :analytics_billable_hours_v2
      def self.query
        TimeEntry.joins(:matter).where(billable: true, written_off: false)
      end
    end
  end
end

The class is the single source of truth. Its query method defines the metric,
its view_name points at the materialized view that pre-computes it, and its
VERSION lets a definition change without silently rewriting history under
reports that depended on the old meaning. Reports never write SQL. They call
the metric class. When the business redefines billable hours, we change one
class, bump the version, and every downstream report inherits the new
definition at once. That is the property none of the alternatives could give
us, because none of them had a single place for the definition to live.

The authorization insight that picked the API

One decision was left over. Reports could have queried the semantic model by
running SQL against its materialized views. We put a GraphQL API in front
instead, and the reason was authorization.

Field-level, firm-scoped authorization in a multi-tenant legal SaaS is not a
thing you want thirty report authors each implementing against raw tables.
Get it wrong in one place and a firm sees another firm's trust balance. If
every report hand-rolls its own permission checks, you have thirty chances to
leak data and no single place to audit. The API layer was the one place to
enforce those rules once, for every consumer, as an invariant rather than a
convention. That is the same logic that ruled out the BI tool, arriving from
the other direction: authorization was non-trivial enough that it wanted to
own an interface, and that interface was the API.

Each layer in the eventual stack earned its place by solving a specific
constraint the alternatives could not. The next post gets concrete about the
metrics model itself: how a named, versioned metric actually behaves, and what
changed the day reports stopped writing SQL.

Ten Reports, Ten Answers: Why Ad-Hoc SQL Doesn't Scale

Son Do — Thu, 23 Jul 2026 09:50:03 +0000

Series -- From Ad-Hoc SQL to a Semantic Layer: 0: Overview · 1: Ten Answers · 2: Why Not Indexes · 3: Metrics Model · 4: View Pipeline · 5: Schema Design · 6: Authorization · 7: Migration Sequence · 8: Stakeholder Alignment

Ad-hoc SQL is the fastest way to ship a report and the slowest way to ship the tenth one. The first few feel like free wins. Someone needs a number, you write a query against the read replica, you hand back a table, everyone moves on. Nobody is thinking about the tenth report while writing the first. But by the time you have thirty, each one has quietly decided for itself what the business words mean, and no two of them decided quite the same way.

I told the front of this story in the overview post: a domain owner pulled me into a call in early 2024 with two reports open side by side, both claiming to show billable hours for the same firm over the same period, and the numbers didn't match. The question on the call was which one was right. I couldn't answer it, and neither could anyone else in the room. This post is about why that call was inevitable, and why the thing that looked like a performance problem turned out to be something worse underneath.

The two queries that measured different things

When I finally pulled up the SQL behind those two billable-hours reports, the divergence was almost boring. One query joined through the billing and invoice tables. It counted hours that had actually been invoiced. The other query hit time_entries directly and counted every entry with a billable status, regardless of whether it had ever made it onto an invoice.

Neither query was wrong. That is the part that took a moment to sit with. The first report was answering "how many billable hours have we invoiced," which is exactly the number you want when you are looking at collections. The second was answering "how many billable hours have our attorneys logged," which is exactly the number you want when you are looking at productivity or work in progress. Two legitimate questions, two correct answers, two reports that both put the label "billable hours" at the top of a column and left the reader to assume they meant the same thing.

The divergence wasn't a bug anyone introduced. It was the natural result of two engineers, at two different times, each making a locally reasonable choice about what "billable" meant and encoding it inline. There was no shared definition to conform to, so each query became its own definition. Multiply that across thirty reports and you don't have thirty queries, you have thirty competing opinions about the vocabulary of the business.

It wasn't just billing

I want to be honest that if this had been a billing-only quirk, we might have papered over it with a footnote and moved on. It wasn't. Once I started auditing, the same pattern showed up everywhere the reports touched a business concept with any nuance.

Active case count was its own small argument. Which case statuses count as "active" is a genuine business question, and different reports had drawn the line in different places, so a firm could see one active-case number on a dashboard and a different one on a summary export. Trust balances, which carry real regulatory weight in legal accounting, could differ depending on which ledger a report queried. Financial summaries produced discrepancies that users noticed and asked about. None of these were exotic edge cases. They were the core numbers firms use to run their practices, and they disagreed with each other in ways that were visible to the people who depended on them.

Three ways this actually hurt

The damage came in three forms, and the order matters because the last one is the one that scared me.

The first was wrong decisions. Firms make real calls on billing and collections data. When the number a firm is looking at depends on which report they happened to open, some of those calls are being made on the wrong figure without anyone knowing it.

The second was operational drag. Because you couldn't trust any single report, the workaround was to cross-check. Domain owners started manually reconciling conflicting reports before they'd share a number with a stakeholder, which is exactly the kind of invisible tax that never shows up in a metrics dashboard but eats hours every week.

The third, and the worst, was the credibility loss. Once a domain owner catches two authoritative reports disagreeing, they stop trusting the reports. They stop trusting all of them, not just the two that disagreed. People began asking for manual verification of numbers the system was supposed to be the source of truth for. That is a slow erosion, not a crash, and it is much harder to recover from than an outage. An outage ends. A reputation for unreliable numbers follows every report you ship afterward.

The index-tuning detour

Here is the part I find most instructive in hindsight, because we got the diagnosis wrong first.

The presenting symptom was latency. The reports were slow, load on the read replica was climbing with every new report, and the obvious move was to make the slow queries faster. So that is what we did. We took the worst-offending queries, added indexes, and tuned them one at a time. It worked. Latency came down, the replica breathed easier, and for about two weeks it felt like we had solved the problem.

Then the next report landed, written from scratch against the production schema like all the others, and the latency and load problems came right back. That was the tell. We were treating the symptoms of one query while the actual disease, the fact that every report re-derived its own definitions and its own access pattern from nothing, was completely untouched. You cannot index your way out of thirty definitions of the same concept. Indexing makes a wrong-but-slow answer into a wrong-but-fast one.

That detour taught me that performance and consistency are different failure modes that happen to look identical from the outside. Both present as slow, unreliable reports. But performance is a downstream problem you fix with faster queries and better caching, and consistency is an upstream problem you fix by moving the definition to a single place before anyone queries it. Optimizing performance downstream of thirty competing definitions doesn't just fail to fix the consistency problem, it locks the mess in by making it cheaper to keep adding to.

What the audit really found

We went into this project to fix performance. Latency was the ticket, the replica load was the pressure, and the two-week index reprieve was the false summit that told us we hadn't found the real thing yet.

What we actually found was definition drift. The reports weren't just slow, they were quietly answering thirty different questions while presenting the answers under the same names. That reframe is the whole reason the rest of this series exists. If the problem had really been latency, a faster database or a caching proxy would have been the end of it. But the meaning of the data lived in thirty places instead of one, and no amount of tuning consolidates meaning.

In the next post I'll get into why we didn't just keep optimizing, and why "add more indexes" and even "add a data warehouse" were the wrong shape of fix for a problem that was really about where a definition is allowed to live.

Why We Chose Permanent Sync Over Migration

Son Do — Thu, 23 Jul 2026 05:29:44 +0000

MyCase Immigration / Docketwise Integration: 0: Why We Synced · 1: Before/After · 2: OAuth2 · 3: Sync vs Migration · 4: Sync Boundary · 5: Family Graph · 6: Write Patterns · 7: Webhooks · 8: Billing

When you are integrating two systems that have overlapping data, migration is the obvious first move. Pick a canonical schema, export from the source, import to the destination, point everything at the new store, and decommission the old one. One system. No sync to maintain. Clean.

We rejected migration for this integration, and the decision was not close.

This post covers why migration was the wrong choice for Docketwise immigration data specifically, and what permanent sync requires by comparison.

What migration would have required

A migration from Docketwise to MyCase would have meant: export all client and case data from Docketwise, transform it to the MyCase schema, import it into MyCase, and make MyCase the sole write system for those records going forward.

This runs into three problems immediately.

The first is that Docketwise's schema has no direct equivalent in MyCase for immigration-specific fields. Visa categories, USCIS form associations, matter types, and typed party role graphs are Docketwise-native concepts. MyCase's schema does not have columns for these. The migration would have required either a MyCase schema extension large enough to model the full immigration domain natively, or a decision to discard immigration-specific data on import.

Neither option was acceptable. A schema extension that imports the full Docketwise immigration model would have turned MyCase into an immigration case management system rather than a practice management system with immigration capabilities. Discarding immigration-specific data on import would have broken active case workflows.

The second problem is Docketwise continuity. Docketwise's standalone product would continue operating. Attorneys who use Docketwise without MyCase would continue creating and updating records in Docketwise. A migration that moved data to MyCase on day 1 would have Docketwise and MyCase diverging immediately. The migrated data in MyCase would be stale the moment any Docketwise user made a change.

The third problem is the definition of "when is migration done." A migration of active case data has no natural completion point. An immigration case is not a closed record; it is an active workflow. A petitioner's address changes. A case receives a USCIS response. A new derivative beneficiary is added. All of those are Docketwise writes that would need to replicate to MyCase after a migration. Which is to say: a migration of active case data is a sync that runs once and then stops, leaving both systems divergent. It does not actually solve the synchronization problem.

Why immigration data is operational, not archival

The migration argument is most compelling for archival data. If Docketwise were only storing completed historical cases, a migration could work. Export the archive, import it to MyCase, stop writing to Docketwise for historical records.

Immigration data is not archival. An active immigration case has a USCIS timeline. Deadlines are live. Form statuses change when USCIS acts. Party relationships are updated when a dependent is added or removed. An attorney querying a case expects the current state, not the state as of the most recent MyCase sync.

The consequence of this is that whoever holds the immigration data must be the system that processes immigration writes. Docketwise handles USCIS form preparation, processes immigration-specific validations, and has the domain logic for immigration case management. Migrating the data to MyCase without migrating that domain logic would have given MyCase a copy of immigration data with no way to correctly process changes to it.

Docketwise was not going to be decommissioned as a write system. That determined the rest of the decision.

The staleness argument

The most direct case against migration was this: a migration on day 1 is stale by day 2.

On day 1, we import all Docketwise data to MyCase. Every Client and Case record in MyCase reflects the state in Docketwise as of the import timestamp. MyCase users see accurate data.

On day 2, an attorney using Docketwise standalone updates a beneficiary's address. Docketwise's record is correct. MyCase's record, the one from the migration, is now wrong. The attorney using MyCase to check that client's contact information has stale data.

A migration that does not include a replication mechanism to keep the two systems in sync after day 1 has exchanged one synchronization problem (manual updates) for a different one (divergent records). The divergent records problem is worse because it is invisible. The attorney using MyCase does not know the data is stale. The attorney using Docketwise does not know that MyCase has old data.

Permanent sync makes the synchronization mechanism explicit and operational from day 1. There is no point at which both systems are assumed to be identical; they are kept current by the sync layer as long as both systems are live.

What permanent sync requires

If both systems are live write systems for their respective domains, the integration requires a synchronization layer that keeps shared records current in both.

The sync layer has three requirements.

The first is a defined boundary. Not all data syncs. The sync covers the records that both systems need for their core workflows. Everything else stays native to its owner. Part 4 covers how we drew that boundary.

The second is source-of-truth partitioning. Even within the records that sync, ownership of specific fields must be clear. When MyCase and Docketwise both have a Client record, and a field on that record is updated in one system, the sync layer needs to know which system's value wins. Partitioning by field domain prevents write conflicts without requiring a distributed locking mechanism.

The third is handling for continuous updates. The sync layer is not a one-time import. Both systems generate events continually. Webhook delivery, ordering failures, and duplicate processing are ongoing concerns. Part 7 covers specifically what went wrong with webhooks in staging and what the fixes were.

What we chose to sync

The sync covers Client and Case records only. These are the entities that both systems need for their core workflows: MyCase for billing and practice management, Docketwise for immigration case work.

The scope of what syncs within Client and Case is narrow: identity fields that both systems need to refer to the same person and the same matter. Part 4 covers the specific boundary in detail.

Everything else stays native. Docketwise owns immigration-specific fields. MyCase owns practice management fields. The sync layer does not attempt to reconcile fields that only one system cares about.

Next: Part 4. Drawing the Sync Boundary: Client and Case Only. Once we chose sync over migration, the next question was what to sync. Not everything that overlaps belongs in the sync boundary. This post covers the test we used to decide what crossed the boundary and what the decision excluded.

Generalizing Addon Billing Without Touching Stripe or Zuora

Son Do — Thu, 23 Jul 2026 05:27:52 +0000

MyCase Immigration / Docketwise Integration: 0: Why We Synced · 1: Before/After · 2: OAuth2 · 3: Sync vs Migration · 4: Sync Boundary · 5: Family Graph · 6: Write Patterns · 7: Webhooks · 8: Billing

When we started building the Immigration addon billing flow, the existing addon billing service was not a service. It was a set of methods tied to a single addon ID.

The billing lifecycle logic (trial, conversion, proration, cancellation) was correct and generally applicable. The binding that made it work only for the Accounting addon was not. This post covers what was hardcoded, what the generalization looked like, and one design decision that was not obvious until we looked at the customer reversion path: Stripe soft-deactivation.

What was hardcoded

The original billing code for addon lifecycle events referenced ACCOUNTING_ADDON_ID as a constant in two places: the service that orchestrated lifecycle events and the background jobs that handled billing transitions.

The lifecycle logic itself handled: trial start, trial expiry, conversion from trial to paid, mid-cycle proration when a firm upgraded mid-month, downgrade handling, and cancellation. None of this logic was specific to Accounting. The same lifecycle applied to any addon that had a trial period and a monthly billing cycle.

What was specific to Accounting: the addon ID used to look up the subscription configuration, the billing interval, and the routing to Stripe. Accounting customers are billed via Stripe. That assumption was buried in the service without a routing decision; the service assumed Stripe without checking which provider was configured for the customer.

The Immigration addon introduced a new variable: some Immigration customers (those converting from Docketwise standalone) would be billed via Zuora, not Stripe. The hardcoded Stripe assumption in the Accounting billing service could not handle them without modification.

The generalization

The generalization had three parts.

First: the billing service became a class that accepts an addon record as its constructor argument. Instead of ACCOUNTING_ADDON_ID embedded in the code, the service looks up addon configuration from what it is passed:

class AddonBillingService
  def initialize(addon:, firm:)
    @addon = addon
    @firm = firm
  end

  def begin_trial
    provider_for_firm.create_trial(
      firm: @firm,
      addon: @addon,
      trial_days: @addon.trial_duration_days
    )
  end

  def convert_to_paid
    provider_for_firm.charge_subscription(
      firm: @firm,
      addon: @addon,
      amount: @addon.monthly_price
    )
  end

  private

  def provider_for_firm
    @firm.billing_provider_zuora? ? ZuoraProvider.new : StripeProvider.new
  end
end

Second: an addons config table with ActiveRecord records. Each row has the same schema: name, trial_duration_days, monthly_price, billing_interval, active. The Accounting addon row was created from the existing constants. The Immigration addon row was added with its own configuration. No code change is required to add a new addon; it requires a new row in the table and a new addon activation flow.

Third: provider routing inside the service. The provider_for_firm method checks which provider is configured for the firm and delegates to ZuoraProvider or StripeProvider accordingly. Neither provider integration was modified. The service is the routing layer; the providers are the execution layer.

The full-switch Stripe soft-deactivation

A specific customer flow required extra handling: a Docketwise standalone customer converting to MyCase Immigration.

Before the integration, these customers had a Docketwise subscription managed through Stripe. When they converted to the MyCase Immigration addon, the active billing relationship moved to Zuora.

The naive approach: cancel the Stripe subscription, create a Zuora subscription, done.

The problem with cancellation: Stripe subscription cancellation permanently ends the billing relationship. If the customer later decided to cancel the MyCase Immigration addon and revert to standalone Docketwise, they would need to re-enter payment details and go through Stripe subscription creation again. Any billing history attached to the original Stripe subscription would be separated from the new one. The reversion path, which we expected some early customers to take, required full re-onboarding through Stripe.

The soft-deactivation approach: instead of canceling the Stripe subscription, we deactivate it. The subscription moves to a cancel_at_period_end state in Stripe. The subscription record is preserved. The payment method is preserved. The billing history stays attached to the original subscription ID.

When the firm's billing period ends, Stripe does not charge. Zuora becomes the active billing relationship for the Immigration addon.

If the customer later cancels the Immigration addon and reverts to standalone Docketwise:

Cancel the Zuora subscription.
Reactivate the Stripe subscription by removing the cancel_at_period_end flag and setting it back to active.
Stripe resumes billing at the next cycle.

The customer sees no re-onboarding flow. Their billing history in Stripe is continuous. Their payment method does not need to be re-entered.

Without soft-deactivation, a customer who converted and then reverted would have needed to start a new Stripe subscription from scratch. That friction was a meaningful deterrent to letting customers try the integrated product. Preserving the reversion path via soft-deactivation made conversion less risky from the customer's perspective, which mattered during the early access period when we expected higher churn than at GA.

The billing transition in code

The convert-to-immigration flow in the Rails backend:

class ConvertToImmigrationAddon
  def initialize(firm:)
    @firm = firm
    @immigration_addon = Addon.find_by!(name: 'immigration')
  end

  def call
    ActiveRecord::Base.transaction do
      soft_deactivate_stripe_subscription
      @firm.update!(billing_provider: :zuora)
      AddonBillingService.new(addon: @immigration_addon, firm: @firm).begin_trial
    end
  end

  private

  def soft_deactivate_stripe_subscription
    return unless @firm.stripe_subscription_id.present?

    StripeProvider.new.deactivate_at_period_end(
      subscription_id: @firm.stripe_subscription_id
    )
  end
end

The transaction wraps the Stripe deactivation, the provider switch, and the Zuora trial creation. If any step fails, the firm remains on Stripe with no changes. Stripe deactivation is called first; if it raises, the firm's provider is not changed and no Zuora subscription is started.

The reversion path:

class RevertToStandaloneDocketwise
  def initialize(firm:)
    @firm = firm
    @immigration_addon = Addon.find_by!(name: 'immigration')
  end

  def call
    ActiveRecord::Base.transaction do
      AddonBillingService.new(addon: @immigration_addon, firm: @firm).cancel
      @firm.update!(billing_provider: :stripe)
      reactivate_stripe_subscription
    end
  end

  private

  def reactivate_stripe_subscription
    return unless @firm.stripe_subscription_id.present?

    StripeProvider.new.reactivate(subscription_id: @firm.stripe_subscription_id)
  end
end

The reactivation calls Stripe's subscription update endpoint to remove the cancel_at_period_end flag. The subscription resumes normal billing.

Regression protection

After the generalization, the Accounting addon continued working. The regression test was: run the Accounting addon's existing billing test suite unchanged and confirm all tests pass.

The test suite covered trial start, conversion, proration, downgrade, and cancellation for the Accounting addon. After the generalization, AddonBillingService received the Accounting addon record as its argument instead of using ACCOUNTING_ADDON_ID directly. The behavior was identical. All tests passed without modification.

This was the validation that the generalization was correctly scoped. The lifecycle logic changed in form (parameterized instead of hardcoded) but not in behavior for the existing case. Adding a new addon did not change what the existing addon did.

What the billing refactor did not touch

The Stripe integration code was not modified. The Zuora integration code was not modified. Neither provider's API client, authentication, or payload construction changed.

The AddonBillingService sits above both provider integrations as an orchestration layer. It makes decisions about lifecycle state (is this firm in a trial? has the trial expired? is this a proration?) and delegates the actual payment operations to whichever provider is appropriate for the firm.

Adding a third addon in the future requires: a new row in the addons config table, a new activation flow, and confirmation that AddonBillingService handles the new addon's configuration correctly. No provider integration changes. No new service class. No new background job types.

The billing generalization satisfied the design constraint without a metric to attach to it. No customer was disrupted during the transition. Both providers kept running. Standalone Docketwise customers converting to MyCase Immigration saw a continuous billing experience. That is what the constraint required.

This is the final post in the series. If you came here for the webhook ordering fix, that is Part 7. If you came for the sync vs. migration decision, that is Part 3. If you came for the family graph schema problem, that is Part 5. Each post stands alone; this post is also where the billing side of the series closes.