Commit c7aac99
committed
feat(quota): implement orchestrator-quota separation and Gemini rate limiting
IMPLEMENTATION: Quota system (Gemini 20 calls/min free tier)
This commit initializes a clean three-layer architecture for quota management:
- Layer 1 (Orchestrator): genieService.process() enforces quota before dispatch
- Layer 2 (Services): ebookService, poetryService, etc. remain quota-unaware
- Layer 3 (Infrastructure): quotaTracker (accounting), geminiClient (tracking)
FILES TO BE ADDED:
- server/utils/quotaTracker.js: Pure accounting module (60-second window)
- server/__tests__/quotaTracker.test.js: Unit tests for quota accounting
FILES TO BE MODIFIED:
- server/geminiClient.js: Add call tracking after successful API responses
- server/genieService.js: Add calculateCostForMode() and quota check to process()
- server/ebookService.js: Remove quota logic (keep pure domain service)
- server/index.js: Add 202 deferral response handling
- server/aiService.js: Pass callIndex parameter through call chain
KEY DESIGN DECISIONS:
✅ Quota check happens ONCE per request (before service dispatch)
✅ Cost calculation centralized (single source of truth)
✅ Only successful API calls are tracked (failures don't count)
✅ Auto-rotating 60-second window (no manual management)
✅ 202 deferral response includes retry-after timing
✅ Domain services remain unaware of quota system
VERIFICATION PLAN:
- quotaTracker unit tests: 3/3 passing
- Cost calculation tests: ebook (10p→6), poetry (1), blog (2000w→4)
- Integration test: 202 deferral + client retry handling
- Edge cases: window rotation, concurrent requests, test isolation
ROLLBACK PATH (if needed):
1. Remove quota check from genieService.process()
2. Remove call tracking from geminiClient
3. Service reverts to unlimited (may hit 429s, but functional)
4. No database changes or migrations needed
RELATED DOCS:
- docs/design/ORCHESTRATOR_QUOTA_SEPARATION.md (architecture)
- docs/design/ORCHESTRATOR_QUOTA_SEPARATION_IMPLEMENTATION.md (step-by-step)
This implementation prevents Gemini 429 (rate limit) errors while maintaining
clean separation of concerns. Future quota policies (per-user limits, priority
queues) can be added to orchestrator without touching domain services.
Branch: feat/quota-system
Status: Ready for engineer implementation (2-3 hour effort)1 parent e0a759b commit c7aac99
0 file changed
0 commit comments