# API Usage Dashboard

## Objective

Show developers what they are calling, how often, and what is failing.

Request volume, error, and latency reporting for an account's API traffic, broken down by key and endpoint.

## 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. Meter every API request at one point in the stack and attribute it to an account, a workspace, and a key. Counting in several places produces numbers that never agree.
2. Break results down by endpoint, status class, and latency percentiles. An average latency hides the tail that is actually hurting people.
3. Deduplicate client retries and internal proxy hops so a single logical call is not counted three times.
4. Show the rate-limit window, the limit, and remaining quota with the reset time, matching the values the API returns in its headers exactly.
5. Do NOT display request or response bodies here. Show method, path template, status, and timing — a usage screen is not a log viewer, and payloads carry customer data.
6. Key creation, scopes, and last-used are owned by API Key Management; limit enforcement and rejection behaviour by Rate Limiting; product analytics by Analytics Dashboard. Link to them instead of restating them.

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

- Group by path template, not by raw URL, or every record ID becomes its own endpoint row.
- Recent buckets are incomplete. Label the current window as partial rather than showing an apparent cliff.
- A deleted or rotated key still has history. Attribute past usage to it without resurrecting the key.
- 4xx caused by the caller and 5xx caused by you must be separated. Merging them makes the developer debug your outage.
- Metering must not sit on the request's critical path. Record asynchronously so instrumentation cannot slow or fail the API.
- High-volume accounts need pre-aggregated rollups; scanning raw request records at read time will be the slowest page in the product.

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

- [ ] Usage is attributable to account, workspace, and individual key.
- [ ] Retries and internal proxy calls are counted once.
- [ ] Breakdowns include endpoint, status class, and latency percentiles.
- [ ] Displayed rate-limit windows and remaining quota match the API's own headers.
- [ ] No request or response payloads appear in the dashboard.
- [ ] The dashboard reads from aggregates and stays fast at high request volume.
- [ ] 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.