Compliance architecture and policy as code
Connect legal requirements to product behavior and retained evidence.
A queued notice is not a completed duty
Enlarge to read every label and explore the connections
Turn obligations into observable states with an owner and completion evidence. Keep failed delivery visible until the required response is complete.
Map the duty to its trigger and completion evidence.
Preserve policy versions and notice content.
Give failed delivery an owned exception route.
The policy says customers receive a notice. The code sends an email. The email bounces. Compliance engineering asks whether the duty was met, what the system knows, and what must happen next.
Build an obligation register
- SourceIdentify the authoritative requirement
- ScopeMap entity product and trigger
- ControlConnect implementation owner and evidence
An obligation register maps a requirement to the entity, product, event, control, owner, evidence, and effective dates. It separates legal requirements, contractual commitments, and internal preferences. This distinction matters when requirements conflict or change.
Use a stable requirement identifier in policy documents, implementation tickets, tests, and audit evidence. A paragraph in a policy is hard to trace if the code uses an unrelated label. Record the authoritative source and the approved interpretation. Engineering should implement a defined obligation rather than improvise legal scope from a brief product request.
An obligation register connects a requirement to the product behavior that satisfies it. The record should identify the authority, covered entity or activity, trigger, required action, responsible owner, evidence, and relevant date. This structure lets an engineer distinguish a product requirement from a general legal reference. It also shows where interpretation is needed before implementation.
A source update can change only one part of the chain. A new effective date may alter when a control begins; a scope change may alter which accounts enter it; a revised notice rule may alter customer communication. Track these dimensions separately. Replacing a paragraph in a policy document is incomplete if the old behavior remains in the service, queue, or message template.
Inside the mechanism. An obligation register should state applicability, triggering event, required action, timing rule, evidence, owner, and change source. A list of law names cannot drive reliable execution. Map obligations to the product and institution that actually perform the activity. Preserve interpretations and effective dates so the system can explain why a workflow applied to a particular customer event.
A concrete example. An obligation becomes implementable when scope, trigger, behavior, timing, ownership, and proof are clear. A link to a rule alone is not a product specification. The case identifies 2,109 eligible records from a source population of 2,850. The required workflow completes for 2,046, but 31 completed records miss the illustrative internal target. Another 63 remain incomplete. Communication evidence covers 2,026 generated notices. Scope, completion, timeliness, and delivery are four separate properties of the customer outcome.
When the assumption fails. A requirement is marked implemented without identifying the affected records or evidence. Map the approved interpretation to observable product states and retained records. The following worked sequence shows the reference condition, a stress condition, and a response condition with explicit synthetic data. These are comparative assumptions, not measured causal effects.
An obligation becomes implementable when scope, trigger, behavior, timing, ownership, and proof are clear. A link to a rule alone is not a product specification.
- Legal requirement
- Applies under the relevant law
- Internal policy
- Additional operating choice made by the firm
Obligation record
Illustrative data; not a real customer record or a prescribed policy.
- IDnotice-014
Stable reference
- Triggerdefined decision event
Starts the workflow
- Evidencenotice version and delivery record
Supports verification
The duty must connect to observable behavior
Trace requirements through code and evidence. The duty must connect to observable behavior.
- Failure mode 1avoid
- Mix law and preference without labels. Change decisions become confused.
- Failure mode 2avoid
- Use an undated source summary. Applicability may change.
- Failure mode 3avoid
- Let a developer infer legal scope alone. Interpretation needs the accountable owner.
Separate rules from orchestration
- RuleDetermine the required action
- WorkflowExecute the action lifecycle
- VersionPreserve which policy governed the event
A policy rule answers a defined question about eligibility or required action. Orchestration manages the sequence of evidence collection, decisions, notices, and follow-up. Mixing them into one large function makes both hard to change safely.
Represent policy versions explicitly. The decision record should identify which version applied at the event time. Use effective dates rather than assuming the newest rule applies to every historical record. When a rule changes, analyze in-flight work as well as new transactions. A mid-case update can otherwise create inconsistent treatment.
Inside the mechanism. Keep the obligation logic separate from the machinery that schedules work, sends messages, and records completion. A workflow engine can execute the wrong rule perfectly. Version both the rule and its implementation, and test the connection between them. Changes need to identify affected open cases, not only new events, because an in-progress obligation may span a release.
A concrete example. The legal or policy condition and the service workflow that applies it can change independently. Mixing them makes both testing and updates harder to explain. The case identifies 2,446 eligible records from a source population of 3,650. The required workflow completes for 2,373, but 36 completed records miss the illustrative internal target. Another 73 remain incomplete. Communication evidence covers 2,349 generated notices. Scope, completion, timeliness, and delivery are four separate properties of the customer outcome.
When the assumption fails. A routing change alters eligibility because the rule is embedded in queue code. Version the decision rule and its execution contract, then verify both at their boundary. The following worked sequence shows the reference condition, a stress condition, and a response condition with explicit synthetic data. These are comparative assumptions, not measured causal effects.
The legal or policy condition and the service workflow that applies it can change independently. Mixing them makes both testing and updates harder to explain.
- Policy evaluation
- Computes a result under a rule
- Workflow execution
- Completes the resulting tasks and evidence
Policy transition
Illustrative data; not a real customer record or a prescribed policy.
- Decision timebefore new rule
Old version may apply
- Notice timeafter release
Workflow continues
- Applied versionrecorded
No silent historical rewrite
Release time and legal applicability can differ
Version rules and handle in-flight work. Release time and legal applicability can differ.
- Failure mode 1avoid
- Apply newest policy to all history. That can rewrite past decisions.
- Failure mode 2avoid
- Hide rules inside notification code. The logic becomes difficult to audit.
- Failure mode 3avoid
- Treat a computed action as completed. Execution may still fail.
Turn requirements into observable states
- PrepareCreate the correct content and recipient
- DispatchUse the approved communication route
- ResolveHandle failure and retain evidence
A required notice can move through prepared, approved, sent, delivery failed, and resolved states. The appropriate completion evidence depends on the actual duty and communication method. A successful API response from an email provider is only one technical event.
Design the workflow with the legal and operations owners. Define retries, alternate channels, deadlines, and escalation. Preserve the exact content and recipient reference under the retention policy. Do not report a notice as complete merely because a job was queued. The difference between intended action and evidenced action is where many compliance defects live.
Observable states make obligations testable. A requirement to investigate an eligible report becomes a sequence of receipt, classification, evidence collection, decision, communication, and any required financial adjustment. Each transition needs a timestamp and a responsible system or person. The exact workflow follows the applicable requirement, but the general engineering principle is stable: evidence must show what happened for the individual case. An aggregate dashboard that says 99% complete cannot explain the remaining customer’s experience.
Inside the mechanism. Translate a requirement into observable states such as eligible, triggered, assigned, pending evidence, completed, delivered, or overdue. Define what evidence permits each transition. A task marked done is weaker than proof that the required customer or external effect occurred. Keep completion time, delivery result, and exceptions separate so operational reporting does not conceal unfinished obligations.
A concrete example. Receipt, classification, investigation, financial adjustment, and communication are distinct events. An aggregate complete flag hides the path the customer experienced. The case identifies 3,605 eligible records from a source population of 4,450. The required workflow completes for 3,497, but 52 completed records miss the illustrative internal target. Another 108 remain incomplete. Communication evidence covers 3,462 generated notices. Scope, completion, timeliness, and delivery are four separate properties of the customer outcome.
When the assumption fails. A case closes before a required adjustment or message is confirmed. Retain each required transition, its timestamp, owner, and completion evidence. The following worked sequence shows the reference condition, a stress condition, and a response condition with explicit synthetic data. These are comparative assumptions, not measured causal effects.
Receipt, classification, investigation, financial adjustment, and communication are distinct events. An aggregate complete flag hides the path the customer experienced.
- Queued
- Work is waiting to run
- Completed duty
- Required action has sufficient evidence under the rule
Notice lifecycle
Illustrative data; not a real customer record or a prescribed policy.
- Contentversion-7
Exact template used
- Provideraccepted
Technical submission
- Deliverybounced
Needs the defined follow-up
A queued job does not prove the duty was met
Model failure and completion evidence explicitly. A queued job does not prove the duty was met.
- Failure mode 1avoid
- Count provider acceptance as every form of legal delivery. The applicable requirement may differ.
- Failure mode 2avoid
- Drop bounced notices. The workflow remains unresolved.
- Failure mode 3avoid
- Retain only the current template. Past content becomes unprovable.
Test the boundary conditions
- Identify boundaryFind facts that change the duty
- Specify outcomeUse approved interpretation
- TestExercise normal and exception paths
Compliance defects often occur at the edges: incomplete applications, changed addresses, weekends, time zones, account closure, or an outage during a deadline. Build tests from the approved requirement, not just the code’s current behavior.
Use examples that vary one legally relevant fact at a time. Record the expected result and source interpretation. Test both the ordinary route and the exception route. A test that repeats the implementation formula can pass while both are wrong. Independent expected cases make the verification meaningful.
Inside the mechanism. Boundary tests should cover the facts that change applicability or timing: product type, account scope, event time, holidays where relevant, incomplete information, reopened cases, and changed ownership. Use expected outcomes derived from the approved rule interpretation. Testing only the typical successful path leaves the most consequential ambiguity unexamined. Record how the system handles an unresolved applicability question.
A concrete example. A control can work for ordinary cases and fail at a cutoff, product change, or missing-data condition. Those boundaries need deliberate evidence. The case identifies 1,016 eligible records from a source population of 1,320. The required workflow completes for 986, but 15 completed records miss the illustrative internal target. Another 30 remain incomplete. Communication evidence covers 976 generated notices. Scope, completion, timeliness, and delivery are four separate properties of the customer outcome.
When the assumption fails. An item exactly at a time or amount boundary follows the wrong branch. Specify inclusivity, time basis, null handling, and the relevant source before implementation. The following worked sequence shows the reference condition, a stress condition, and a response condition with explicit synthetic data. These are comparative assumptions, not measured causal effects.
A control can work for ordinary cases and fail at a cutoff, product change, or missing-data condition. Those boundaries need deliberate evidence.
- Implementation mirror
- Repeats what the code already does
- Requirement test
- Checks a separately specified expected behavior
Boundary test
Illustrative data; not a real customer record or a prescribed policy.
- Inputaddress changed mid-case
Relevant event
- Expectedapproved routing behavior
Requirement-defined result
- Evidencedelivered fixture and state
Observable outcome
Passing code-shaped tests can still miss the duty
Test independently specified outcomes. Passing code-shaped tests can still miss the duty.
- Failure mode 1avoid
- Test only the happy path. Exceptions often carry the defect.
- Failure mode 2avoid
- Ignore time zones. Date boundaries can alter behavior.
- Failure mode 3avoid
- Use production customer records as fixtures. Synthetic cases can test the rule.
Manage corrections as customer events
- IdentifyDefine and review the affected population
- RemedyExecute approved corrective actions
- ReconcileConfirm each record has an outcome
When a compliance defect affects customers, fixing the code is only part of the work. Identify the affected population, determine the appropriate remedy, execute it, and verify completion. Preserve the difference between potential and confirmed impact.
Use a reproducible population query with reviewed assumptions. Reconcile remediation records against that population. Track failed contacts and exceptions. A release note saying fixed does not show whether past customers received the required correction. The final evidence should connect the original defect, affected records, remedy, and remaining unresolved work.
Inside the mechanism. A correction can require more than changing a database value. Identify the affected customer population, financial effects, notices, records, and downstream decisions. Preserve the original error and the corrective action as linked events. Reconcile the completed remediation against the eligible population and account for failed delivery or unresolved amounts. A closed engineering ticket is not proof that every customer received the correction.
A concrete example. Preventing a future defect does not resolve customers already affected by it. The correction needs a reproducible population and a verified outcome. The case identifies 2,190 eligible records from a source population of 2,380. The required workflow completes for 2,124, but 32 completed records miss the illustrative internal target. Another 66 remain incomplete. Communication evidence covers 2,103 generated notices. Scope, completion, timeliness, and delivery are four separate properties of the customer outcome.
When the assumption fails. A fixed release closes the incident while earlier balances and notices remain wrong. Identify affected records, assess amounts and messages, perform approved corrections, and reconcile closure. The following worked sequence shows the reference condition, a stress condition, and a response condition with explicit synthetic data. These are comparative assumptions, not measured causal effects.
Preventing a future defect does not resolve customers already affected by it. The correction needs a reproducible population and a verified outcome.
- Code repair
- Stops the defect in future processing
- Customer remediation
- Addresses the consequences of past failures
Remediation record
Illustrative data; not a real customer record or a prescribed policy.
- Potentially affected1200
Initial population
- Confirmed affected940
Reviewed scope
- Completed932
Eight remain unresolved
A code fix does not repair past harm by itself
Verify remediation against the affected population. A code fix does not repair past harm by itself.
- Failure mode 1avoid
- Close after deployment. Historical cases may remain.
- Failure mode 2avoid
- Assume potential impact equals confirmed impact. The scope needs evidence.
- Failure mode 3avoid
- Ignore failed remediation attempts. Those customers still need resolution.
Chapter connections
Continue with Consumer protection, errors, and complaints to follow the next part of the system. Use the glossary for terminology and risk mathematics for formulas and worked calculations.