# Credit Billing — What
## Overview
Credit-based billing for AI features. Users purchase credits,
each AI action costs a specific amount.
## Glossary
- **Credit**: Virtual currency, 1 credit = $0.01
- **Cost Map**: Lookup table mapping AI actions to credit costs
## Must-Haves
### M-1: Credit Deduction on AI Action
- **Priority**: P0 (must)
- **User Story:** As a user, I want to see exactly how many
credits each AI action costs before it runs.
#### Acceptance Criteria
1. WHEN an AI action is requested, THE system SHALL check
the user's credit balance against the action's cost.
- Example: balance=50, cost=10 → allow, new balance=40
2. IF balance < cost, THEN THE system SHALL reject with HTTP 402.
- Example: balance=3, cost=10 → HTTP 402
{required: 10, current: 3}
## Edge Cases
| Scenario | Expected Behavior |
|----------|-------------------|
| balance = 0 | Block, show purchase prompt |
| Concurrent requests | Serialize via SELECT FOR UPDATE |
| Webhook timeout | Don't add credits, log for reconcile |
| Cost map changes mid-flight | Use cost at request start time |
# Credit Billing — How
## Overview
Credit check and deduction via dedicated service layer.
Uses database row-level locking (SELECT FOR UPDATE).
**Key Design Decisions:**
- Row-level locking over mutexes (survives crashes)
- Immutable ledger (balance derived from ledger sum)
- Cost map cached in Redis (admin updates without deploys)
## Architecture
```mermaid
sequenceDiagram
participant C as Client
participant A as API
participant S as CreditService
participant D as Database
C->>A: POST /api/v1/generate-report
A->>S: check_and_deduct(user_id, action)
S->>D: SELECT FOR UPDATE balance
D-->>S: balance = 50
alt balance >= cost
S->>D: INSERT ledger + UPDATE balance
S-->>A: {success: true, balance_after: 40}
else balance < cost
S-->>A: {success: false, required: 10}
end
```
## Existing Code to Reuse
| What | File Path | How to Reuse |
|------|-----------|-------------|
| StripeWebhookHandler | services/payment/stripe.py | Add credit top-up |
| UserModel | models/user.py | Add credit_balance |
## Correctness Properties
### Property 1: Balance Never Negative
*For any* sequence of concurrent deductions, balance SHALL
never go below 0.
**Validates: M-1, Q-2**
# Credit Billing — Now
## Action Items
- [ ] 1. Database: Create ledger table
- [ ] 1.1 Create Alembic migration `add_credit_billing`
- Add `credit_balance INTEGER DEFAULT 0` to users
- Create `credit_ledger` table
- _Ref: M-1.3_
- [ ] 2. Checkpoint — Database ready
- Run `alembic upgrade head`
- [ ] 3. Service layer
- [ ] 3.1 Create `services/billing/credit_service.py`
- `CreditService.check_and_deduct(db, user_id, action)`
- Use SELECT FOR UPDATE for row locking
- _Ref: M-1.1_
- [ ] 4. Checkpoint — Service layer ready
- Unit test: check_and_deduct() with mock DB
- [ ] 5. API
- [ ] 5.1 Add credit check to AI endpoints
- _Ref: M-1.1_
- [ ] 6. Tests
- [ ] 6.1 Unit tests
- [ ] 6.2 Property tests (Hypothesis)
- [ ] 6.3 Integration tests
- [ ] 7. Final checkpoint — All tests pass
## Dependency Graph
```json
{
"waves": [
{ "id": 0, "tasks": ["1.1"] },
{ "id": 1, "tasks": ["3.1"] },
{ "id": 2, "tasks": ["5.1"] },
{ "id": 3, "tasks": ["6.1", "6.2", "6.3"] }
]
}
```
