--- id: t7-multi-municipality-architecture title: Multi Municipality Architecture module: GROW-S6 module_slug: grow-s6-govtech-compliance cluster: Trust type: spec version: v0.1.0 status: Gate-reviewed tier: membership contract_role: "" canonical_url: "https://grow.goodcombinator.ai/library/registry/t7-multi-municipality-architecture" download_url: "https://grow.goodcombinator.ai/library/registry/t7-multi-municipality-architecture.md" license: CC-BY-4.0 (proposed — owner confirmation required) source: GROW by Good Combinator retrieved_at: 2026-05-29 --- # Multi-Municipality Architecture Spec Deploying a compliance agent across more than one jurisdiction without a principled architecture produces one of two failure modes: a brittle single-tenant build that cannot be adapted without rewriting core logic, or a sprawling one-off-per-jurisdiction implementation where every new municipality is a fresh project. This spec defines the alternative: a shared core workflow with a configuration layer that holds jurisdiction-specific rules, forms, thresholds, and approval flows, plus a jurisdiction-overlay mechanism for cases where a municipality's rules conflict with or extend the universal baseline. The result is a compliance agent that can serve South Walton County today, a neighboring special district tomorrow, and a multi-county stormwater authority the day after — with the shared logic tested once and the jurisdiction-specific content reviewed by the appropriate local authority. Hard-coding a jurisdiction value into compliance logic is forbidden under this architecture; jurisdiction is always a runtime parameter resolved from the configuration layer. ## 1. Three-Layer Architecture The architecture has three layers, each with distinct ownership, update cadence, and review authority. ``` ┌─────────────────────────────────────────────────────────┐ │ Layer 3: Jurisdiction Overlay │ │ Conflicts, extensions, exceptions for a specific │ │ jurisdiction that override Layer 2 behavior │ │ Owner: local jurisdiction authority + district counsel │ │ Update cadence: triggered by rule change │ └─────────────────────────────────────────────────────────┘ ↑ extends / overrides where declared ┌─────────────────────────────────────────────────────────┐ │ Layer 2: Jurisdiction Configuration │ │ Active rule set, thresholds, forms, deadlines, │ │ approval flows — all populated from t7-jurisdiction- │ │ rule-map for the target jurisdiction │ │ Owner: compliance workflow operator │ │ Update cadence: per t7-rule-change-tracker │ └─────────────────────────────────────────────────────────┘ ↑ parameterizes ┌─────────────────────────────────────────────────────────┐ │ Layer 1: Core Compliance Workflow │ │ Phase logic, determination engine, C9 emission, │ │ HITL gate rules, exception handling — jurisdiction- │ │ agnostic, parameterized by Layer 2 │ │ Owner: GROW Library (t7-compliance-workflow) │ │ Update cadence: per GROW Library semver │ └─────────────────────────────────────────────────────────┘ ``` ### Layer 1 — Core Compliance Workflow The core workflow (`t7-compliance-workflow`) implements the five-phase process model, the C9 emission logic, the HITL gate triggers, and the exception-handling paths. It receives a `jurisdiction_config` object at runtime and executes phases entirely on the basis of that config. It contains zero hard-coded jurisdiction values — no specific statute citations, no specific threshold numbers, no specific form IDs. **Layer 1 invariants (must hold across all jurisdictions):** 1. `expert_review_required: true` always raises an S1 HITL event and always blocks applicant output. 2. A determination with `decision_origin: compliance-determination` is only emitted for rule rows that are within the agent's deterministic classification authority. 3. Any `rule_id` not found in the active jurisdiction config produces `determination: needs-review`, not a default `not-applicable`. 4. `retention_class: civic-7yr` is applied to all compliance provenance records regardless of jurisdiction. 5. The "not legal advice" disclaimer is appended to all applicant-facing outputs regardless of jurisdiction. ### Layer 2 — Jurisdiction Configuration The jurisdiction configuration is a structured object loaded at agent initialization. It is the runtime materialization of the relevant rows from `t7-jurisdiction-rule-map` for a specific `jurisdiction_id` plus any cross-cutting universal rules. **Jurisdiction configuration schema:** ```yaml jurisdiction_config: jurisdiction_id: display_name: effective_date: config_version: reviewer_role_map: engineering: legal: administrative: rules: - rule_id: active: threshold_overrides: {} # if blank, use rule-map defaults form_ids: [] deadline_days: intake_schema: applicant_notice_template: appeal_path: # [ATTORNEY REVIEW] retention_schedule_ref: ``` **Population rule.** The jurisdiction configuration is populated by extracting rows from `t7-jurisdiction-rule-map` where `jurisdiction_id` matches AND scope is `universal`, combined with local rows for the same jurisdiction. A configuration may not reference a `rule_id` that does not exist in the map; adding a rule to a config requires adding it to the map first. ### Layer 3 — Jurisdiction Overlay An overlay is a structured exception declared by the local jurisdiction authority. It may extend Layer 2 (add a rule unique to this municipality) or override a Layer 2 threshold, form, or deadline. Overlays are the controlled mechanism for local variation; they replace ad hoc modifications to the core workflow. **Overlay schema:** ```yaml jurisdiction_overlay: jurisdiction_id: overlay_id: overlay_version: effective_date: authorized_by: attorney_review: true # all overlays require attorney review [ATTORNEY REVIEW] changes: - type: rule_id: field: prior_value: new_value: rationale: citation: verify_flag: true # overlays always carry [VERIFY] ``` **Overlay safety rules:** - An overlay may not suppress a rule that has `attorney_review: true` in the jurisdiction map without a documented counsel sign-off. - An overlay may not remove the `expert_review_required` flag from a rule that already carries it. - Overlays are version-controlled; the active overlay for a jurisdiction is tracked in `t7-rule-change-tracker` as a distinct `change_type: rule-extension` or `rule-suppression` item. ## 2. Multi-Jurisdiction Deployment Pattern **Step 1 — Baseline audit.** Before deploying to a new jurisdiction, run a jurisdiction audit: pull all universal-scope rule rows from `t7-jurisdiction-rule-map`, confirm `last_confirmed` dates, and flag any with `verify_flag: true`. The audit produces a gap list. **Step 2 — Local rule population.** For the new jurisdiction, add `scope: local` rows to `t7-jurisdiction-rule-map` covering the jurisdiction's local ordinances, forms, and approval flows. Each new row requires a `last_confirmed` date and a reviewer-role attestation. **Step 3 — Build Layer 2 config.** Populate the `jurisdiction_config` object, referencing only `rule_id` values now present in the map. **Step 4 — Overlay review.** If the jurisdiction has local variations that modify universal rules, document them as Layer 3 overlays. Each overlay requires `[ATTORNEY REVIEW]` before activation. **Step 5 — Test.** Run the operational test harness (defined in `t7-govtech-package`) against the new config using jurisdiction-specific test cases. Pass/fail criteria are the same as the baseline; the config, not the core logic, absorbs jurisdiction variation. **Step 6 — Go-live.** Activate the config. The core workflow executes unchanged. ## 3. Preventing Hard-Code Drift Hard-coding jurisdiction values into the core workflow — a statute citation, a form ID, a threshold number — is the most common cause of multi-municipality breakage. The architecture prevents it through structural rules, not code review alone. **Lint rules (enforced at CI):** 1. The `t7-compliance-workflow` artifact text must not contain any specific statute citation, form ID, or numerical threshold. Statutes and thresholds live in the jurisdiction map; the workflow references `rule_id` values only. 2. The jurisdiction config schema must validate that every `rule_id` in the config resolves to a row in `t7-jurisdiction-rule-map` at deployment time. 3. Any change to the core workflow that adds a jurisdiction-specific string is a gate-failing CI violation. **Review check.** At each `t7-rule-change-tracker` quarterly review, a multi-jurisdiction reviewer role confirms that no new hard-codes have crept into the core workflow or the shared codebase. ## 4. Worked Example — Expanding from South Walton County to Okaloosa County **Scenario.** GoodSam AI deploys the stormwater pre-screener in South Walton County (Walton County `jurisdiction_id: fl-walton-county`). A neighboring Okaloosa County special district requests the same capability. The expansion requires no changes to the core workflow. **Expansion checklist:** 1. Jurisdiction audit for Okaloosa County: confirm universal rules are current. Both `fdep-stormwater-general` and `fl-pub-records-access` carry over unchanged (universal scope). 2. Local rules for Okaloosa County identified: Okaloosa County Land Development Code, Okaloosa County Stormwater Ordinance, and OWCD (Okaloosa Water & Sewer District) intake process. Each gets a new `rule_id` and `scope: local` rows added to `t7-jurisdiction-rule-map` with `jurisdiction_id: fl-okaloosa-county`. `[VERIFY]` on all new rows. 3. `jurisdiction_config` built for `fl-okaloosa-county`: universal rules included, local rules included. 4. Overlay review: Okaloosa County has a shorter notice period for certain permit classes. Overlay `oc-overlay-001` is created: `type: deadline-override`, `rule_id: okaloosa-co-ldco`, `prior_value: 90`, `new_value: 60`. `[ATTORNEY REVIEW]` obtained from district counsel. 5. Test cases run against `fl-okaloosa-county` config. Walton County config remains unchanged and continues serving its existing applications. 6. Go-live: two active configs, one core workflow, one rule map with both jurisdiction sets. **What did NOT change:** the C9 emission logic, the HITL gate trigger conditions, the aggregation logic, the "not legal advice" disclaimer, the retention class. These are Layer 1 invariants. **What changed:** two config objects, six new rule-map rows, one overlay. Total new artifacts: contained and jurisdiction-scoped. ## 5. Config Versioning and Compatibility Each `jurisdiction_config` carries a `config_version` semver. A config version bump is triggered by: - A new rule being added to the active set (MINOR). - A threshold, form, or deadline changing within an existing rule (MINOR). - A rule being removed from the active set (MAJOR — requires `[ATTORNEY REVIEW]`). - The `intake_schema` pointer changing (MINOR if backward-compatible, MAJOR if not). Config version mismatches between a running workflow and the loaded config are a `schema-drift-input` failure mode per `s1-failure-mode-register` and route to HITL.