Skip to content

User Stories

US1: Connect AI Provider & View Usage Analytics (P1)

A developer signs up, connects their OpenAI/Anthropic/OpenRouter API key, and sees a dashboard with token usage breakdowns (per-model, daily, cached vs. uncached) and estimated CO2 emissions. This works on the free tier without any payment.

Why P1

The free analytics dashboard is the acquisition funnel. Without standalone value at the free tier, there's no path to paid conversion. This story proves the core pipeline (connect → poll → calculate → display) works end to end.

Independent test: Connect a real provider key, wait for the hourly poll (or trigger manual sync), and verify the dashboard shows token counts within ±15% of the provider's native dashboard, with CO2 estimates and cached/uncached split.

Acceptance Scenarios

  • Given a new user with an OpenAI admin API key, when they register the key via the connections API, then the system validates the key against OpenAI's usage API and stores only the Secrets Manager ARN.
  • Given an active connection, when the hourly polling cron fires, then the system polls the provider, deduplicates events via idempotency hash, and calculates emissions for each new event.
  • Given ingested telemetry, when the user views the dashboard overview, then they see total CO2e, per-model breakdown, daily chart, and cached vs. uncached token split.
  • Given a free-tier user, when they view offset-related features, then they see an "Upgrade to offset" CTA instead of receipts.

US2: Upgrade to Paid & Receive Carbon Receipts (P2)

A developer upgrades to a paid tier (Starter $29/mo), and at billing cycle close the system retires real carbon credits against their period's emissions and delivers a cryptographically signed receipt with a branded PDF. Any third party can verify the receipt independently.

Why P2

This is the revenue path. Without working billing and receipt generation, there's no business.

Independent test: Upgrade an account via Stripe test mode, ensure enough telemetry exists for the period, trigger billing close, and verify: receipt with valid serial number exists, Ed25519 signature verifies via the public endpoint, PDF downloads correctly, credit serial numbers reference real inventory.

Acceptance Scenarios

  • Given a free-tier user, when they upgrade to Starter, then the system creates a Stripe subscription and transitions the org to the paid tier.
  • Given a paid-tier org with usage data, when the billing period closes (invoice.payment_succeeded + T+48h reconciliation window), then the system aggregates CO2, retires credits, generates a signed receipt, and produces a PDF.
  • Given a signed receipt, when anyone hits the public verification endpoint, then they receive the receipt metadata, signature, and public key for independent verification.
  • Given late-arriving telemetry after period close, when the event's timestamp falls in a closed period, then it's recorded as a prior-period adjustment in the next open period.

US3: Organize Workloads by Project (P3)

A developer with multiple AI applications creates projects and maps connections to them, so the dashboard shows per-project emissions breakdowns and the receipts can reference specific projects.

Why P3

Project organization adds real analytics value but isn't required for the core pipeline or billing to work.

Independent test: Create two projects, map different connections to each, ingest telemetry, and verify project-level breakdowns aggregate only the correct workloads. Export CSV filtered by project.

Acceptance Scenarios

  • Given a user with a connected provider, when they create a project and re-map the connection, then future events route to a new workload under that project while historical events stay.
  • Given multiple projects with telemetry, when the user views a project detail page, then they see only that project's per-model breakdown, daily chart, and CO2 totals.
  • Given a user with projects, when they export CSV, then the export includes project_name and can be filtered by project.

US4: Monthly Audit Pack for Compliance (P3)

A compliance officer downloads a monthly audit pack (zip) containing all receipts, calculation breakdowns, retirement confirmations, and methodology version for CSRD reporting.

Why P3

Enterprise upsell feature. Not needed for initial launch but critical for Growth/Scale/Enterprise tiers.

Independent test: Complete at least one billing cycle with receipts, trigger audit pack generation, download the zip, and verify contents match the manifest.

Acceptance Scenarios

  • Given a paid-tier org with completed billing periods, when the monthly audit pack cron runs (3rd of month), then the system generates a zip with receipts, calculations, and methodology.
  • Given an audit pack exists, when the user downloads it, then the zip contents match the manifest and all receipts inside verify independently.

US5: SDK, MCP & CLI Integration (P4)

A developer integrates carbon tracking into their CI/CD pipeline using the Python SDK, or uses the MCP server from their AI IDE, or runs CLI commands to check status and export data.

Why P4

Phase 2. Only begins after Phase 1 acceptance criteria are met and paying users exist.

Independent test: Use the Python SDK to call cl.telemetry.summary() and cl.receipts.verify(), verify responses match the REST API.

Acceptance Scenarios

  • Given a published OpenAPI spec, when a developer installs the TypeScript or Python SDK, then they can query telemetry and verify receipts with less than 50ms overhead per call.
  • Given an MCP server running, when a developer calls estimate_emissions or list_receipts tools, then they get correct responses consuming only the REST API.

Edge Cases

Scenario Expected behavior
Provider API key is revoked mid-cycle System sets connection to "error" status, stops polling, notifies user
Provider returns revised usage data for a previous bucket Upsert strategy updates token counts while preserving the idempotency hash key
Stripe payment fails Billing period set to "failed", no credits retired, user notified
Insufficient credit inventory Billing close job fails gracefully, alerts operations, receipts deferred
5+ consecutive permanent failures on a connection Connection skipped during polling until user re-authenticates
T+48h reconciliation reveals significantly different data Updated calculations included before receipt generation since receipts are deferred by 48h

Cross-References

Success Criteria

ID Criterion
SC-001 Users can connect a provider and see usage data within 2 hours of signing up
SC-002 Token count accuracy within ±15% of the provider's native dashboard over a 7-day window
SC-003 Cached token usage produces materially lower CO2 estimates than equivalent uncached usage
SC-004 Receipt verification confirms valid signature for 100% of generated receipts
SC-005 Free tier provides standalone analytics value: per-model breakdowns, daily granularity, cached/uncached split, CSV/JSON export
SC-006 Billing upgrade from free to paid completes without errors and triggers automated credit retirement
SC-007 Late-arriving telemetry (6+ hour delay) is correctly assigned to the proper billing period with no double-counting
SC-008 3+ design partners connected by day 30, 2+ paying customers by day 60
SC-009 Dashboard initial load under 3 seconds, API p95 response time under 200ms
SC-010 Zero P0 bugs at launch, all P1 bugs documented with timeline