# Amplitude Event Tracking

## Objective

Send behavioural events to Amplitude with stable users, devices, and account grouping.

A server-side pipeline that forwards behavioural events, user properties, and account-level groupings to Amplitude.

## 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. Identify the behaviours worth measuring and emit them from one place in the application layer, so that the set of events is readable in a single file rather than inferred by grepping the codebase.
2. Establish the identity model before writing any send code: what identifies a signed-in user, what identifies a device or anonymous session, and how the two are stitched at sign-up and sign-in.
3. Map the app's own tenancy — workspace, organisation, or team — onto Amplitude's group concept, and derive it from the record the event belongs to rather than from whatever context the request happened to carry.
4. Send through the app's existing background-job system with a deterministic per-event identifier so retries, offline replays, and queue redeliveries collapse to a single recorded event.
5. This overlaps Mixpanel Event Tracking. If both are being applied, the event catalogue, the anonymous-to-known stitching, and the deduplication identifiers belong to a shared internal layer; only the transport, the group mapping, and the credential belong to this brief.

## 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

- The transition from anonymous to authenticated must carry the earlier session forward exactly once. Stitching on every subsequent request re-attributes history repeatedly and inflates activation numbers.
- User properties describe the person now; event properties describe the moment. Sending the current plan as a user property and then reading it back as if it applied historically produces confidently wrong retention analysis.
- Group identifiers must come from the tenant that owns the record. Attaching a user's default workspace to an event that actually happened in another workspace makes per-account metrics untrustworthy in exactly the accounts that matter most.
- Server retries and any offline client queue can both replay the same event. Deduplication has to key on something the app generated at the moment of the action, not on arrival time or a sequence counter.
- High-cardinality properties such as raw IDs, full URLs with query strings, or free text will exhaust property limits and make charts unusable. Bucket them or leave them out.
- Sensitive fields must never travel as properties. Assume anything sent is retained beyond the app's own deletion process and cannot be recalled.
- When the destination rate-limits or returns errors, back off with jitter and cap the queue. An unbounded retry loop against a degraded endpoint will take down the worker pool that also runs email and billing jobs.
- A user who withdraws consent must stop generating events immediately, and the app needs a path to request deletion of what was already sent.

## 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

- [ ] Events are emitted from one declared catalogue rather than ad hoc call sites.
- [ ] Anonymous and authenticated activity are stitched once per session transition, with no repeated re-attribution.
- [ ] Group identifiers always reflect the tenant that owns the underlying record.
- [ ] Duplicate deliveries from retries or offline replay resolve to a single event.
- [ ] No high-cardinality or sensitive value is sent as a property.
- [ ] Destination errors and rate limits produce bounded, backed-off retries that never fail the originating user action.
- [ ] Consent withdrawal halts transmission and is recorded so deletion can be requested.
- [ ] 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.