salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6e2101d019c3ab1e91bf41ff5fb5c2a9705f088e
igny8/PLAN-LIMITS-IMPLEMENTATION.md
IGNY8 VPS (Salman) 6e2101d019 feat: add Usage Limits Panel component with usage tracking and visual indicators for limits 
style: implement custom color schemes and gradients for account section, enhancing visual hierarchy
2025-12-12 13:15:15 +00:00

14 KiB
Raw Blame History

Plan Limits Implementation Checklist

Version: v1.1.0 (Minor version - new feature)
Started: December 12, 2025
Status: In Progress

📋 Overview

Implementing comprehensive plan limit system to enforce pricing tier limits for:

  • Hard limits (persistent): sites, users, keywords, clusters
  • Monthly limits (reset on billing cycle): content ideas, words, images, prompts

Phase 1: Backend Setup ✅ / ❌

1.1 Plan Model Updates

  • Add max_keywords field to Plan model
  • Add max_clusters field to Plan model
  • Add max_content_ideas field to Plan model
  • Add max_content_words field to Plan model
  • Add max_images_basic field to Plan model
  • Add max_images_premium field to Plan model
  • Add max_image_prompts field to Plan model
  • Add help text and validators for all fields
  • Update __str__ method if needed

File: backend/igny8_core/auth/models.py

1.2 PlanLimitUsage Model Creation

  • Create new PlanLimitUsage model
  • Add fields: account, limit_type, amount_used, period_start, period_end
  • Add Meta class with db_table, indexes, unique_together
  • Add __str__ method
  • Add helper methods: is_current_period(), remaining_allowance()

File: backend/igny8_core/business/billing/models.py

1.3 Database Migration

  • Run makemigrations command
  • Review generated migration
  • Test migration with migrate --plan
  • Run migration migrate
  • Verify schema in database

Command: python manage.py makemigrations && python manage.py migrate

1.4 Data Seeding

  • Create data migration for existing plans
  • Populate limit fields with default values (Starter: 2/1/100K, Growth: 5/3/300K, Scale: Unlimited/5/500K)
  • Create initial PlanLimitUsage records for existing accounts
  • Calculate current usage from existing data

File: backend/igny8_core/business/billing/migrations/00XX_seed_plan_limits.py

1.5 Word Counter Utility

  • Create word_counter.py utility
  • Implement calculate_word_count(html_content) function
  • Strip HTML tags using BeautifulSoup or regex
  • Handle edge cases (empty content, None, malformed HTML)
  • Add unit tests

File: backend/igny8_core/utils/word_counter.py

1.6 Content Model Auto-Calculation

  • Update Content model save() method
  • Auto-calculate word_count when content_html changes
  • Use word_counter.calculate_word_count()
  • Test with sample content

File: backend/igny8_core/business/content/models.py

1.7 LimitService Creation

  • Create limit_service.py
  • Implement check_hard_limit(account, limit_type) - sites, users, keywords, clusters
  • Implement check_monthly_limit(account, limit_type, amount) - ideas, words, images, prompts
  • Implement increment_usage(account, limit_type, amount, metadata)
  • Implement get_usage_summary(account) - current usage stats
  • Implement get_current_period(account) - get billing period
  • Create custom exceptions: HardLimitExceededError, MonthlyLimitExceededError
  • Add logging for all operations
  • Add unit tests

File: backend/igny8_core/business/billing/services/limit_service.py

1.8 Update PlanSerializer

  • Add all new limit fields to PlanSerializer.Meta.fields
  • Test serialization
  • Verify API response includes new fields

File: backend/igny8_core/auth/serializers.py

1.9 Create LimitUsageSerializer

  • Create PlanLimitUsageSerializer
  • Include all fields
  • Add computed fields: remaining, percentage_used

File: backend/igny8_core/business/billing/serializers.py

Phase 2: Backend Enforcement ✅ / ❌

2.1 Hard Limit Enforcement - Sites

  • Update SiteViewSet.create() to check max_sites
  • Use LimitService.check_hard_limit(account, 'sites')
  • Return proper error message if limit exceeded
  • Test with different plan limits

File: backend/igny8_core/auth/views.py

2.2 Hard Limit Enforcement - Users

  • Update user invitation logic to check max_users
  • Use LimitService.check_hard_limit(account, 'users')
  • Return proper error message if limit exceeded

File: backend/igny8_core/auth/views.py (UserViewSet or invitation endpoint)

2.3 Hard Limit Enforcement - Keywords

  • Update keyword creation/import to check max_keywords
  • Check before bulk import
  • Check before individual creation
  • Use LimitService.check_hard_limit(account, 'keywords')

File: backend/igny8_core/business/planning/views.py

2.4 Hard Limit Enforcement - Clusters

  • Update clustering service to check max_clusters
  • Check before AI clustering operation
  • Use LimitService.check_hard_limit(account, 'clusters')

File: backend/igny8_core/business/planning/services/clustering_service.py

2.5 Monthly Limit Enforcement - Content Ideas

  • Update idea generation service
  • Check max_content_ideas before generation
  • Increment usage after successful generation
  • Use LimitService.check_monthly_limit() and increment_usage()

File: backend/igny8_core/business/planning/services/idea_service.py or similar

2.6 Monthly Limit Enforcement - Content Words

  • Update content generation service
  • Check max_content_words before generation
  • Use Content.word_count for actual usage
  • Increment usage after content created
  • Sum word counts for batch operations

File: backend/igny8_core/business/content/services/content_generation_service.py

2.7 Monthly Limit Enforcement - Images

  • Update image generation service
  • Check max_images_basic or max_images_premium based on model
  • Increment usage after image created
  • Track basic vs premium separately

File: backend/igny8_core/business/content/services/image_service.py or similar

2.8 Monthly Limit Enforcement - Image Prompts

  • Update image prompt extraction
  • Check max_image_prompts before extraction
  • Increment usage after prompts extracted

File: backend/igny8_core/business/content/services/ (wherever prompts are extracted)

2.9 Automation Pipeline Integration

  • Update automation to check limits before each stage
  • Show limit warnings in pre-run estimation
  • Stop automation if limit would be exceeded
  • Log limit checks in activity log

File: backend/igny8_core/business/automation/services/

Phase 3: Monthly Reset Task ✅ / ❌

3.1 Celery Task Creation

  • Create reset_monthly_plan_limits() task
  • Find accounts with billing period ending today
  • Reset PlanLimitUsage records
  • Create new records for new period
  • Log reset operations
  • Handle errors gracefully

File: backend/igny8_core/tasks/billing.py

3.2 Celery Beat Schedule

  • Add task to CELERY_BEAT_SCHEDULE
  • Set to run daily at midnight UTC
  • Test task execution

File: backend/igny8_core/celery.py

3.3 Manual Reset Capability

  • Create admin action to manually reset limits
  • Add to PlanLimitUsageAdmin
  • Test manual reset

File: backend/igny8_core/business/billing/admin.py

Phase 4: API Endpoints ✅ / ❌

4.1 Limits Usage Endpoint

  • Create /api/v1/billing/limits/usage/ endpoint
  • Return current usage for all limit types
  • Return remaining allowance
  • Return days until reset
  • Include plan limits for reference
  • Test endpoint

File: backend/igny8_core/business/billing/views.py

4.2 Limits History Endpoint (Optional)

  • Create /api/v1/billing/limits/history/ endpoint
  • Return historical usage data
  • Support date range filtering
  • Test endpoint

File: backend/igny8_core/business/billing/views.py

Phase 5: Frontend Updates ✅ / ❌

5.1 Update Plan Interface

  • Add limit fields to Plan interface in billing.api.ts
  • Add limit fields to Plan interface in Settings/Plans.tsx
  • Add limit fields to Plan interface in SignUpFormUnified.tsx
  • Add limit fields to Plan interface in AuthPages/SignUp.tsx
  • Ensure consistency across all 4 locations

Files: Multiple interface definitions

5.2 Create PlanLimitsWidget Component

  • Create PlanLimitsWidget.tsx component
  • Display hard limits (Sites, Users, Keywords, Clusters) with counts
  • Display monthly limits with progress bars
  • Show days until reset
  • Fetch from /api/v1/billing/limits/usage/
  • Add refresh capability
  • Style with existing design system

File: frontend/src/components/dashboard/PlanLimitsWidget.tsx

5.3 Update Dashboard

  • Add PlanLimitsWidget to dashboard
  • Position alongside CreditBalanceWidget
  • Test responsive layout

File: frontend/src/pages/Dashboard/Dashboard.tsx or similar

5.4 Update Settings/Plans Page

  • Display all limit fields in plan cards
  • Format numbers (1,000 / 100K / Unlimited)
  • Update extractFeatures() function
  • Test plan display

File: frontend/src/pages/Settings/Plans.tsx

5.5 Update Usage Page

  • Add limits section to Usage page
  • Display current usage vs limits
  • Show limit types (hard vs monthly)
  • Add progress bars for monthly limits
  • Test with real data

File: frontend/src/pages/Billing/Usage.tsx

5.6 Create Limit Exceeded Modal

  • Create LimitExceededModal.tsx component
  • Show when limit is reached
  • Display current usage and limit
  • Show upgrade options
  • Link to billing page
  • Style with existing modal pattern

File: frontend/src/components/billing/LimitExceededModal.tsx

5.7 Add Limit Guards

  • Check limits before operations (optional - server-side is primary)
  • Show limit exceeded modal on API error
  • Handle HardLimitExceededError and MonthlyLimitExceededError
  • Display user-friendly messages

Files: Various page components

Phase 6: Admin & Testing ✅ / ❌

6.1 Django Admin for PlanLimitUsage

  • Create PlanLimitUsageAdmin class
  • Add list display fields
  • Add filters (account, limit_type, period)
  • Add search fields
  • Add readonly fields (created_at, updated_at)
  • Add custom actions (reset, export)
  • Register admin

File: backend/igny8_core/business/billing/admin.py

6.2 Update Plan Admin

  • Add new limit fields to PlanAdmin
  • Group fields logically (Hard Limits, Monthly Limits)
  • Add inline for related limit usage (optional)
  • Test admin interface

File: backend/igny8_core/auth/admin.py

6.3 Backend Testing

  • Test hard limit checks
  • Test monthly limit checks
  • Test limit increment
  • Test monthly reset
  • Test word count calculation
  • Test API endpoints
  • Test error handling

6.4 Frontend Testing

  • Test plan display with limits
  • Test limits widget
  • Test usage page
  • Test limit exceeded modal
  • Test responsive design
  • Test with different plan tiers

6.5 Integration Testing

  • Test complete workflow: create content → check limits → increment usage
  • Test monthly reset → verify limits reset
  • Test upgrade plan → verify new limits apply
  • Test limit exceeded → verify operation blocked
  • Test across different accounts and sites

Phase 7: Documentation ✅ / ❌

7.1 Update CHANGELOG

  • Document all changes
  • List new fields added
  • List new services created
  • List API endpoints added
  • List frontend components added
  • Update to v1.1.0

File: CHANGELOG.md

7.2 Update API Documentation

  • Document /api/v1/billing/limits/usage/ endpoint
  • Document error responses
  • Add examples

File: docs/20-API/BILLING-ENDPOINTS.md

7.3 Update Feature Guide

  • Document plan limits feature
  • Document limit types
  • Document monthly reset
  • Add to features list

File: IGNY8-COMPLETE-FEATURES-GUIDE.md

Phase 8: Deployment ✅ / ❌

8.1 Pre-Deployment Checklist

  • All migrations created and tested
  • All tests passing
  • No console errors in frontend
  • CHANGELOG updated
  • Version bumped to v1.1.0
  • Code reviewed

8.2 Deployment Steps

  • Backup database
  • Run migrations
  • Deploy backend
  • Deploy frontend
  • Verify limits working
  • Monitor for errors

8.3 Post-Deployment Validation

  • Test limit checks work
  • Test usage tracking works
  • Test monthly reset (wait or trigger manually)
  • Verify no existing functionality broken
  • Monitor error logs

📊 Progress Summary

Total Tasks: ~80
Completed: 2
In Progress: 1
Not Started: 77

Estimated Time: 8-12 hours
Started: December 12, 2025
Target Completion: December 13, 2025

🔍 Testing Scenarios

Scenario 1: Hard Limit - Sites

  1. Account with Starter plan (max 2 sites)
  2. Create 2 sites successfully
  3. Try to create 3rd site → should fail with limit error

Scenario 2: Monthly Limit - Content Words

  1. Account with Starter plan (100K words/month)
  2. Generate content totaling 99K words
  3. Try to generate 2K words → should fail
  4. Wait for monthly reset
  5. Generate 2K words → should succeed

Scenario 3: Monthly Reset

  1. Account at end of billing period
  2. Has used 90% of limits
  3. Run reset task
  4. Verify usage reset to 0
  5. Verify new period created

Scenario 4: Plan Upgrade

  1. Account on Starter plan
  2. Reached 100% of limit
  3. Upgrade to Growth plan
  4. Verify new limits apply
  5. Perform operation → should succeed

⚠️ Known Risks & Mitigation

Risk 1: Breaking existing content generation
Mitigation: Test thoroughly, use feature flags if needed

Risk 2: Word count inconsistency
Mitigation: Use single source (Content.word_count), standardize calculation

Risk 3: Monthly reset errors
Mitigation: Add error handling, logging, manual reset capability

Risk 4: Performance impact of limit checks
Mitigation: Optimize queries, add database indexes, cache plan data

📝 Notes

  • Use Content.word_count as single source of truth for word counting
  • Ignore estimated_word_count in Ideas and word_count in Tasks for limit tracking
  • Hard limits check COUNT from database
  • Monthly limits track usage in PlanLimitUsage table
  • Reset task must be idempotent (safe to run multiple times)
  • All limit checks happen server-side (frontend is informational only)
  • Use proper error classes for different limit types
  • Log all limit operations for debugging
Reference in New Issue View Git Blame Copy Permalink