AI Workloads Platform¶

Carbon emissions tracking and offsetting for AI inference workloads.

Reading Order¶

Start with the Proposal for context, then follow the path that matches your goal:

Goal	Reading path
Understanding the product	Proposal → User Stories → Requirements
Building it	Design → Data Model → API Contract → Tasks → Quickstart
Understanding decisions	Research → Design
Writing tests	Domain Specs → API Contract → Quickstart

Document	Role	Summary
Proposal	Why and what changes	Start here for context
User Stories	Who uses it and how	User narratives, acceptance scenarios, success criteria
Requirements	What the system must do	Sections 1-11 covering all functional requirements
Domain Specs	How to verify it works	BDD scenarios (GIVEN / WHEN / THEN)
Research	Why we chose this approach	Decision log (R1-R9) with alternatives considered
Design	How it's built	Architecture, components, error mapping, project structure
Data Model	What data exists	11 entity schemas with columns, indexes, constraints
API Contract	How to call it	Every endpoint with request/response shapes
Tasks	When to build what	Phase 1 and 2 task breakdown with requirement traceability
Quickstart	How to run it	Local setup, smoke tests, verification points

Four standalone Mermaid diagrams are embedded throughout the documentation:

Diagram	Location	Contents
System Context	Design	High-level system context (external services, AWS, frontend)
Telemetry Pipeline	Design	Data flow: polling → ingestion → emissions calculation
Billing & Receipt Pipeline	Design	Data flow: Stripe webhook → billing close → receipt signing → PDF
Entity Relationship	Data Model	Relationships across all 11 tables

Each piece of information lives in exactly one document. Other documents cross-reference rather than duplicate.

Information	Canonical location
Functional requirements (sections 1-11)	Requirements
Entity schemas, indexes, constraints	Data Model
Architecture decisions with rationale (R1-R9)	Research
Implementation-level decisions	Design
Error-to-HTTP mapping	Design
API endpoint shapes and examples	API Contract