Knowledge transfer
Named artifacts, each with a City recipient and a documented walkthrough, accepted before final payment. Runbooks are written for a reader who was not present during implementation.
| Artifact | Kind | City recipient | Walkthrough | Format | Status |
|---|---|---|---|---|---|
| Architecture decision record (ADR-001 to ADR-014) | Architecture decision record | Kevin Tran, Data Engineer | 11/04/2026 | Markdown in the CDR repository | Accepted |
| Runbook: nightly load and failure recovery | Operational runbook | Kevin Tran, Data Engineer | 10/30/2026 | Markdown | Accepted |
| Runbook: quarantine review and release | Operational runbook | Data stewards (each department) | 10/30/2026 | Markdown | Accepted |
| Runbook: source mapping change (schema drift) | Operational runbook | Kevin Tran, Data Engineer | 11/07/2026 | Markdown | Accepted |
| Runbook: restore from backup and failover test | Operational runbook | IT Infrastructure Manager | 10/22/2026 | Markdown | Accepted |
| Runbook: month end consumption report | Operational runbook | Data and Innovation Administrator | 11/03/2026 | Markdown | Accepted |
| Access administration procedure (grant, review, revoke) | Access procedure | IT Security Officer | 10/28/2026 | Word | Accepted |
| Pipeline documentation: Tyler Munis | Pipeline documentation | Kevin Tran, Data Engineer | 10/30/2026 | Markdown | Accepted |
| Pipeline documentation: EnerGov | Pipeline documentation | Kevin Tran, Data Engineer | 11/07/2026 | Markdown | Accepted |
| Pipeline documentation: Cityworks, 311, CAD, ArcGIS, SharePoint | Pipeline documentation | Kevin Tran, Data Engineer | 11/13/2026 | Markdown | Scheduled |
| How to add the next source system | Pipeline documentation | Kevin Tran, Data Engineer | 11/13/2026 | Markdown | Scheduled |
| Department training deck and exercises | Training materials | Training coordinator, Human Resources | 10/14/2026 | PowerPoint and Word (editable) | Accepted |
| Metric definitions (13 migrated measures) | Metric documentation | Office of Data and Innovation | 11/05/2026 | Markdown and catalog | Accepted |
| CDR policy | Policy | Assistant City Manager | 11/20/2026 | Word | Draft for review |
Operational runbooks
RB-01 Nightly load and failure recovery (Daily, 02:00)
- Open Pipeline runs and check the latest run status.
- If a step failed, open the run and read the step detail.
- Fix the cause (credentials, network, source outage).
- Re-run from the failed step: python -m cdr.orchestrate run <time>. Watermarks prevent duplicates.
- Confirm the alert closes on the next run.
RB-02 Quarantine review and release (Daily)
- Open Quarantine and filter to your department.
- Read the rule and the held record.
- Correct the record in the source system, or document an accepted exception.
- The next run releases the record automatically once it passes.
- Records held more than 10 days are raised to the Data and Innovation Administrator.
RB-03 Source mapping change (schema drift) (When an alert of category Schema drift opens)
- Read the alert: it names the missing column and what the source exposes now.
- Confirm with the system owner (vendor release notes).
- Add a new mapping version with the new column; never edit an old version.
- Schedule a replay from the last good watermark.
- After the next run, confirm quarantine released and reconciliation passes.
RB-04 Restore from backup and failover test (Quarterly)
- Pick the latest verified nightly snapshot.
- Restore to the paired region test environment.
- Run the reconciliation suite against production values.
- Record RPO and RTO achieved on the Operations page.
- File the test record with IT.
RB-05 Month end consumption report (Monthly, first business day)
- Open Cost and consumption.
- Check each workload class against its monthly budget.
- Review compute that ran without auto suspend.
- Export the monthly report and send to the Assistant Director.
- Raise sizing changes as a change request.
Architecture decision record
| Decision | Alternatives considered | Why |
|---|---|---|
| ADR-001 Medallion layout: raw, cleansed, curated Raw keeps every extracted version; cleansed keeps the newest version passing blocking rules; curated serves departments. | Single staging schema; vendor-managed data hub. | Lets the City replay history and explain every number. |
| ADR-004 Quarantine instead of load-and-flag Records failing a blocking rule are held out of curated until corrected. | Load everything with a flag column. | Departments never see a value that conflicts with the source of record. |
| ADR-007 Versioned source mappings with replay A mapping change creates a new version and a replay window; old versions stay readable. | Edit mappings in place. | Schema changes (vendor upgrades) are recoverable without a full reload. |
| ADR-009 Metrics as code with written definitions Every metric has a definition and the SQL that computes it; both are versioned together. | Metrics defined in the BI tool only. | Values can be reproduced and verified independently of the report. |
| ADR-011 Roles, not people, carry access Access requests name a position and role; people are added to Entra ID groups. | Grant access to named users. | Matches the RFI requirement and survives staff turnover. |
| ADR-014 Separate compute per workload class with auto suspend Ingestion, transformation, BI serving and ad hoc analysis use separate compute, each with auto suspend. | One shared warehouse. | Costs are attributable and predictable. |
Change log
| When | Who | Area | Change | Ticket |
|---|---|---|---|---|
| 11/07/2026 06:15 | Kevin Tran | Quarantine | Confirmed all 115 held EnerGov permits released by the replay; DS-01 and DS-02 reconcile again. | CDR-2291 |
| 11/06/2026 09:42 | Kevin Tran | energov_permit replay | Published source mapping v4 (IssueDate) for EnerGov permits and scheduled a replay from the 11/05 02:00 watermark. | CDR-2291 |
| 11/06/2026 07:52 | Kevin Tran | Alert | Acknowledged schema drift alert on EnerGov permits. | CDR-2291 |
| 11/03/2026 09:10 | Kevin Tran | Cost | Lowered BI serving auto suspend from 15 to 10 minutes after the October report. | CDR-2274 |
| 10/28/2026 08:40 | Marisol Ortega | Access | Approved AR-0412 (Department Analyst, Utilities) for position 4410. | AR-0412 |
Data as of run R-20261111-0200, finished 11/11/2026 02:13 Central. Curated layer: curated schema.