Make state explicit
Define what the customer, appointment, order, task, and financial workflow can become—and which transitions are valid.
Back to selected work
Healthcare Journey Systems
How I translate messy customer journeys into product and engineering contracts that are measurable, reliable, and safe to operate.
01 · The boundary
Technical product ownership, stated precisely.
My work sat where journey metrics, operating workflows, product behavior, and backend contracts meet. I needed enough technical depth to define states and edge cases, challenge system behavior, instrument outcomes, and make trade-offs with engineering.
Authorship boundaryThis is a sanitized systems study based on production product experience. I am not claiming sole authorship of the company’s backend architecture or implementation.
Specify the contract
Align on actors, inputs, outputs, errors, duplicate behavior, side effects, and instrumentation before a flow is built.
Close the metric loop
Connect backend outcomes to customer funnels, service quality, workload, revenue, cost, and operating alerts.
02 · Architecture
One journey crosses many product and system boundaries.
A useful architecture view shows responsibilities and handoffs. It does not expose proprietary endpoints or infrastructure.
System context
The whole operating system around a customer journey
The experience layer stays coherent because domain modules, durable data, asynchronous work, partner adapters, and observability are designed together.
Experience layer
Patient, provider, care, and operations surfaces share the same underlying journey state instead of creating channel-specific truth.
Contract layer
Versioned APIs validate identity, role, input, current state, and expected outcome before a command reaches domain logic.
Domain layer
Journey, appointment, fulfilment, payout, outbound, and task modules own their rules and expose deliberate handoffs.
Reliability layer
Durable data, caches, locks, events, queues, scheduled work, audit history, and traces keep workflows recoverable.
03 · API design
An API is a product promise between systems.
For a booking, chatbot escalation, payout approval, or fulfilment update, the endpoint name is the smallest part of the design. The meaningful work is making the behavior unambiguous.
Request lifecycle
The synchronous decision and asynchronous aftermath
Commit the core business outcome once, return a stable response, then execute messages, tasks, webhooks, and analytics through durable asynchronous paths.
Who may act?
Authentication identifies the actor; roles, context, and consent determine whether that actor may perform this action.
Is the request valid?
Typed request objects define required fields, formats, safe defaults, and specific validation errors.
Is the transition allowed?
Domain rules check eligibility and current state—for example, whether a slot is still available or a payout is approvable.
What if it repeats?
An idempotency key, stable business identifier, or deduplication rule prevents duplicate bookings, messages, and ledger entries.
What happens next?
The contract names synchronous output plus the events, timers, tasks, webhooks, and analytics emitted after a successful write.
How does it fail?
Expected errors, timeouts, retries, dead-letter handling, operator visibility, and safe replay are designed before launch.
04 · Events & state
The system needs memory and a clock.
Current state answers “where is this journey now?” Events answer “what happened?” Scheduled events answer “what should happen later?” Keeping these ideas separate makes the flow debuggable.
Journey orchestration
State, events, timers, and consumers work together
A transition can update customer state immediately and schedule future work without forcing the user-facing request to wait for every side effect.
- State guards prevent impossible transitions, such as completing a cancelled appointment or approving an already-paid ledger item.
- Timers model reminders, eligibility windows, callbacks, and expiry as durable work—not fragile in-process delays.
- Consumers remain idempotent so a retry can safely produce the intended outcome once.
05 · Schema design
Design data for decisions, traceability, and change.
The schema should make the most important product questions easy to answer without sacrificing operational or financial auditability.
Conceptual entity model
The journey episode is the connective tissue
Stable relationships let teams connect customer intent, operational work, delivery, financial outcomes, messages, and analytics without relying on a single overloaded table.
Use one stable identifier for every core entity and preserve the source reference from partner systems.
Model relationships explicitly so a journey can be traced from person to episode, appointment, order, invoice, payout, message, and outcome.
Keep current state easy to query, while recording the event or audit history needed to explain how it changed.
Index the paths used by live products and operating dashboards; do not optimize only for storage neatness.
Keep financial and audit records append-safe. Corrections should create traceable adjustments instead of silently rewriting history.
Use flexible JSON attributes for genuinely variable metadata—not as a substitute for stable, queryable product concepts.
06 · Reliability
Design the recovery path before launch.
Reliability becomes a product concern when a duplicate task wastes an agent’s time, a lost message breaks treatment continuity, or a repeated ledger write moves money twice.
Prevent
Validate state, lock scarce resources, use stable identifiers, make consumers idempotent, and release through feature flags.
Recover
Retry transient failures, route exhausted work to a dead-letter queue, preserve context, and provide safe replay or manual action.
Observe
Connect logs, traces, queue depth, error classes, journey funnels, service SLAs, and business guardrails to one incident picture.
Metric hierarchySystem health: latency, error rate, queue age, duplicate rate → journey health: completion, drop-off, turnaround time → business health: conversion, repeat revenue, workload, cost, and margin.
07 · My contribution
What I owned—and where engineering owned implementation.
Clear boundaries make the case study more credible and show how I collaborate in a production team.
AreaMy product contributionEngineering contribution
Journey and state design
Defined customer states, entry and exit criteria, edge cases, ownership, and the metric attached to each transition.
Implemented domain services, persistence, concurrency controls, migrations, tests, and runtime deployment.
APIs and integrations
Specified actors, payload needs, success and error behavior, duplicate handling, downstream events, and partner handoffs.
Selected implementation patterns, wrote controllers and adapters, handled authentication, and maintained service contracts.
Reliability and rollout
Prioritized failure modes, manual fallbacks, alerts, support visibility, feature flags, and business guardrails.
Built queues, locks, retries, dead-letter paths, traces, dashboards, and operational tooling.
Production outcomes
View operating evidenceSee how these systems decisions moved customer and business metrics.
All diagrams are original, sanitized conceptual representations. No patient data, source code, internal endpoint names, credentials, or proprietary infrastructure details are included.