Segment Events Instrumentation

The Problem

The company’s recording operations process hundreds of thousands of eRecording packages per year across multiple pathways — AI-agent-driven and human-specialist-driven — yet there was no shared way to measure how long a package takes to move from assembly to recorded document. Each system tracked its own slice: operator handle time, task completion, vendor acceptance. None answered the question that actually mattered: how long does it take end-to-end? Three major program launches were converging simultaneously — an AI recording agent, a new UI platform, and standardized APIs — and all of them needed this measurement to prove success. Without it, the program had no way to answer “is this working?” with data.

The Solution

I delivered a unified analytics event stream that tracks every recording package through its full lifecycle — from creation through vendor submission, county recording, and artifact return — regardless of whether a human or AI agent initiated the work. For the first time, the organization can measure true end-to-end recording time in days (not just operator minutes), compare AI agent performance directly against human specialists on the same metric, diagnose where time is being spent across the workflow, and attribute rejection rates at the individual document level.

Outcome & Impact

The instrumentation established measurement capability that did not previously exist anywhere in the organization. The event stream enables the first cross-system end-to-end time-to-record metric, covering days of calendar time rather than minutes of operator handle time. It provides the first direct comparison substrate between AI agent and human specialist performance on the same metric — the data foundation for the program’s parity claim. Per-document rejection attribution answers “which document types get rejected most, by which counties?” from the event stream alone. An attempt-number dimension on submission events tracks rework without requiring new event types. Both recording pathways — human and agentic — share the same seven-event schema, so new host applications can adopt the standard without schema negotiation.

My Role & Contributions

Aspect	Detail
Role	Sole architect and implementer
Team size	1
Timeline	~1 month
Scope	Event taxonomy implementation, analytics governance negotiation, full implementation across backend API and frontend UI repositories
Key decisions	Event registration and governance negotiation; actor attribution architecture; per-document fan-out strategy; identity resolution approach

Technical Overview

Human UI ──────────┐                        ┌── Segment ── Amplitude
                   ├── Recording API ───────┤
AI Agent ──────────┘   (NestJS backend)     └── Data Warehouse
                             │
                    Recording UI (Next.js)
                             │
                     Segment (client-side)

The instrumentation spans two repositories. On the backend, I built greenfield Segment SDK integration into an API that had zero analytics infrastructure. A middleware chain uses Node.js AsyncLocalStorage to propagate caller identity — whether the request originated from an AI agent or a human — through the entire request lifecycle without requiring changes at individual controller or service call sites. A separate middleware extracts user identity from JWT tokens for Segment’s identity resolution requirements.

The most architecturally interesting piece is the per-document event fan-out: a single rejection webhook from the county or vendor triggers individual events for each document in the package, because counties act on documents rather than packages. This granularity unlocks rejection-rate-by-document-type analytics that package-level events can’t provide.

On the frontend, I built a React analytics context with a declarative tracking hook and configured the UI to inject an actor-type header on all recording API calls, enabling the backend to attribute every action to its source pathway without inspecting auth tokens.

Business Events Implemented

Event	Grain	Trigger
Package Created	Package	Package assembled for recording
Package Ready	Package	Approved for submission
Package Submitted	Package	Handed to eRecording vendor (carries attempt number)
Package Rejected	Package	Vendor or county returns for correction
Document Recorded	Document	County records individual document
Document Returned	Document	Recorded artifact received back from vendor
Document Rejected	Document	Per-document rejection attribution

Challenges & Key Decisions

Governance negotiation was the critical path, not the code

The implementation itself was straightforward. The hardest work was mapping recording-workflow concepts to the organization’s established analytics conventions and getting non-standard event types approved by the product analytics governance team. The team had an established naming convention, property contracts, and collision-prevention governance. Several proposed events conflicted with existing ones; one required adopting an existing contract and adding recording-specific fields as optional extensions rather than creating a parallel event family. All recording-specific properties initially used one casing convention; the governance standard required another, and non-compliant properties would have been silently stripped by the analytics pipeline. Starting the collision audit and property-naming review earlier would have let the registration lead time run in parallel with development.

Implementing for two pathways simultaneously

The agentic pathway alone would have been simpler to instrument. Working from a shared schema defined by the sr. PM, I built the instrumentation to support both pathways from the start — same event envelope, same properties, different actor-dimension values — rather than staging the human pathway as a follow-on. This meant the human pathway required zero schema changes to add later; it extends the agentic implementation by populating dimension values, not by introducing new event types.

Async attribution without auth-system coupling

For notification-driven events (rejection webhooks, document returns) where no live HTTP request carries actor context, I hardcoded the actor type for the pilot period based on known traffic composition, with a post-pilot path to look up actor type from stored package metadata. This kept the pilot simple without painting the system into a corner.

Tech Stack

Layer	Technologies
Backend	NestJS, Node.js, TypeScript
Frontend	Next.js, React, TypeScript
Analytics	Segment, Amplitude

Lessons Learned

• Organizational negotiation is the critical path. Analytics governance at enterprise scale means the hardest work is political, not technical. Running the collision audit and naming review concurrently with implementation would have saved two weeks.
• AsyncLocalStorage is underrated for cross-cutting concerns. The middleware → context service → analytics service chain propagated identity cleanly with zero changes at call sites throughout the codebase.
• Implement for the pair, not the solo. Choosing to instrument both pathways simultaneously — rather than staging the human pathway — meant the second pathway was a zero-schema-change extension when it arrived, not a retrofit.