# Segment Event Forwarding

## Objective

Send one clean stream of product events to Segment and let it fan out downstream.

A documented event schema and a single forwarding path emitting track, identify, group, and page calls with consistent identity.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Write the event schema before writing any code: the exact set of event names, the properties each carries with their types, and the traits attached to a user and to an account. Every downstream tool inherits this schema, so a name chosen carelessly is expensive to change later.
2. Establish one identity model and apply it everywhere. Use a stable internal user identifier that never changes, associate the anonymous identifier from the first visit with it at signup, and attach the account or workspace so downstream tools can roll events up by customer.
3. Route every event through one internal emitter rather than calling the provider from feature code. That emitter validates the event against the schema, drops or flags anything unrecognised, and is the single place where identity and default properties are attached.
4. Assign each event a single origin, browser or server, and document it in the schema. Prefer the server for anything that must be accurate — purchases, plan changes, provisioning — and leave the browser for interactions only it can see.
5. Since Segment fans out to marketing and support tools, treat every property as though a downstream operator will read it. Never send credentials, payment details, message contents, or anything a user typed that was not intended for analysis, and honour the app's existing consent handling before emitting.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Without a fixed track, identify, group, and page schema, event names drift into near-duplicates and every downstream report has to be rebuilt. Keep the schema in version control, validate against it at emit time, and treat a new event name as a deliberate change.
- The same event emitted from both the browser and the server is counted twice in every destination it reaches, and the two copies will carry different identity. Declare one origin per event and enforce it in the emitter.
- Consent settings and per-destination rules are configured in the provider's workspace and in the app, and the two must agree. Do not emit before consent is resolved on the assumption that a downstream filter will catch it.
- Traits and properties travel further than the analytics warehouse — into email tools, support consoles, and advertising platforms. Restrict them to an allowed list and keep sensitive values out entirely.
- Delivery retries must not change an event's identity or its recorded timestamp. Set the timestamp at the moment the event occurred, carry a stable message identifier so a redelivery is deduplicated, and do not renumber or reorder a queued batch on retry.
- Ordering is not guaranteed end to end. An event referring to an entity must carry enough context to stand alone, because the identify or group call establishing that entity may arrive after it.
- An anonymous session that is never linked to a signup leaves the pre-signup activity stranded. Perform the alias or association at the moment of account creation, not later.
- When the provider is unavailable, buffer with a bounded queue and back off with jitter. Analytics delivery must never block a user request, and dropped events should be counted so the loss is visible.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] A versioned event schema defines every event name, property, and trait, and the emitter validates against it.
- [ ] All events leave through a single internal emitter rather than direct calls from feature code.
- [ ] Each event has one declared origin and is never sent from both the browser and the server.
- [ ] Identity is consistent: a stable internal user identifier, the anonymous identifier associated at signup, and the account attached to every event.
- [ ] No credential, payment detail, or sensitive user content appears in any property or trait.
- [ ] Retried deliveries carry the original timestamp and a stable message identifier, and are deduplicated downstream.
- [ ] Consent is resolved before emission, and a provider outage degrades to a bounded buffer with visible dropped-event counts.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.