motovaultpro/backend/src/features/subscriptions/CLAUDE.md

backend/src/features/subscriptions/

Stripe payment integration for subscription tiers and donations.

Files

File	What	When to read
README.md	Feature overview with architecture diagram	Understanding subscription flow

Subdirectories

Directory	What	When to read
api/	HTTP controllers and routes	API endpoint changes
domain/	Services and type definitions	Business logic changes
data/	Repository for database operations	Database queries
external/stripe/	Stripe API client wrapper	Stripe integration
migrations/	Database schema	Schema changes
jobs/	Scheduled background jobs	Grace period processing

Key Patterns

• Repository mapRow() converts snake_case to camelCase
• Webhook idempotency via stripe_event_id unique constraint
• Tier sync to user_profiles.subscription_tier on changes
• Grace period: 30 days after payment failure
• Vehicle selections for tier downgrades (not deleted, just gated)

API Endpoints

Subscriptions (Authenticated)

• GET /api/subscriptions - Current subscription
• POST /api/subscriptions/checkout - Create subscription
• POST /api/subscriptions/cancel - Schedule cancellation
• POST /api/subscriptions/reactivate - Cancel pending cancellation
• POST /api/subscriptions/downgrade - Downgrade with vehicle selection
• PUT /api/subscriptions/payment-method - Update payment
• GET /api/subscriptions/invoices - Billing history

Donations (Authenticated)

• POST /api/donations - Create payment intent
• GET /api/donations - Donation history

Webhooks (Public)

• POST /api/webhooks/stripe - Stripe webhook (signature verified)

Configuration

Secrets (files via config-loader)

• /run/secrets/stripe-secret-key - Stripe API secret key
• /run/secrets/stripe-webhook-secret - Stripe webhook signing secret

Environment Variables (docker-compose)

• STRIPE_PRO_MONTHLY_PRICE_ID
• STRIPE_PRO_YEARLY_PRICE_ID
• STRIPE_ENTERPRISE_MONTHLY_PRICE_ID
• STRIPE_ENTERPRISE_YEARLY_PRICE_ID