9.1 KiB
Tenancy System Implementation - START HERE
Complete Specification with Database Context
Status: ✅ Ready for Implementation
Database Analyzed: ✅ Yes (5 plans, 8 accounts, working credit system)
Code Context: ✅ Complete (all models, flows, permissions documented)
Critical Issues: ✅ 4 identified and specified
Implementation Plan: ✅ 10 phases with exact code
🎯 What This Folder Contains
This folder has EVERYTHING needed for 100% accurate implementation:
1. Database State (FROM PRODUCTION)
- ✅ 5 existing plans (free, starter, growth, scale, enterprise)
- ✅ 8 accounts actively using the system
- ✅ 280+ credit transactions (system working)
- ✅ User-Account-Site relationships CONFIRMED
- ✅ What fields exist vs missing (e.g., payment_method MISSING)
2. Complete Requirements
📄 FINAL-IMPLEMENTATION-REQUIREMENTS.md
- ✅ 4 critical issues documented with fixes
- ✅ Strict rules for plan allocation
- ✅ Subscription date accuracy rules
- ✅ Superuser session contamination fix
- ✅ Docker build cache issue resolution
3. Implementation Guide
📄 FINAL-IMPLEMENTATION-PLAN-COMPLETE.md
- ✅ 10 phases with exact code
- ✅ File locations and line numbers
- ✅ Verification steps for each phase
- ✅ Rollback strategies
4. Specific Fixes
📄 FREE-TRIAL-SIGNUP-FIX.md - Signup simplification
📄 COMPLETE-IMPLEMENTATION-PLAN.md - Original gaps
5. Reference Documents
📄 Final_Flow_Tenancy.md - Target flows
📄 Tenancy_Audit_Report.md - Audit report
📄 audit_fixes.md - Previous recommendations
📄 tenancy-implementation-plan.md - Original plan
🚨 4 Critical Issues (MUST FIX)
Issue A: Plan Allocation Inconsistency
Problem: Multiple fallback paths, enterprise auto-assigned, 0 credits
Fix: Strict free-trial → free → error (no other fallbacks)
Status: Code updated, needs plan creation + deployment
Issue B: Subscription Dates Inaccurate
Problem: Trial/activation/renewal dates not calculated correctly
Fix: Strict date rules (no gaps, no overlaps)
Status: Needs implementation in serializer + billing endpoint
Issue C: Superuser Session Contamination
Problem: Regular users get superuser access via session cookies
Fix: JWT-only for API, block session auth, detect and logout superuser
Status: 🔥 CRITICAL - Needs immediate fix
Issue D: Docker Build Cache
Problem: Router errors after deployment, fixed by container rebuild
Fix: Use --no-cache, exclude node_modules volume, npm ci
Status: Needs Dockerfile and compose updates
📊 Current Database State (Verified)
Plans
✅ free - $0, 100 credits
✅ starter - $89, 1,000 credits
✅ growth - $139, 2,000 credits
✅ scale - $229, 4,000 credits
✅ enterprise - $0, 10,000 credits
❌ free-trial - MISSING (needs creation)
Accounts
8 total accounts
├─ 3 active (paying)
├─ 5 trial (testing)
└─ Credits: 0 to 8,000 range
Users
8 users (1 developer + 7 owners)
All have account assignments
Role system working correctly
Missing in Database
❌ Account.payment_method field
❌ Subscription.payment_method field
❌ Subscription.external_payment_id field
❌ Any Subscription records (0 exist)
🔧 Code Changes Already Made
⚠️ Review Before Deploying
Backend
auth/serializers.py:276- RegisterSerializer.create() updated
- Auto-assigns free-trial plan
- Seeds credits = plan.get_effective_credits_per_month()
- Sets account.status = 'trial'
- Creates CreditTransaction log
- ⚠️ Still needs: Enterprise protection, Subscription creation with dates
Frontend
components/auth/SignUpForm.tsx- Removed plan selection UI
- Changed to "Start Your Free Trial"
- Removed plan_id from registration
- Redirect to /sites instead of /account/plans
Management
auth/management/commands/create_free_trial_plan.py- Command to create free-trial plan (2000 credits)
🚀 Implementation Steps (When Ready)
Step 1: Critical Fixes First (Day 1)
# 1. Create free-trial plan
docker exec igny8_backend python manage.py create_free_trial_plan
# 2. Fix superuser contamination (see FINAL-IMPLEMENTATION-REQUIREMENTS.md Issue C)
# 3. Fix Docker build cache (see FINAL-IMPLEMENTATION-REQUIREMENTS.md Issue D)
# 4. Test signup
# Visit https://app.igny8.com/signup
# Should create account with 2000 credits, status='trial'
Step 2: Payment System (Day 2-3)
Follow FINAL-IMPLEMENTATION-PLAN-COMPLETE.md Phases 1-5
Step 3: Tests & Deploy (Day 4-7)
Follow FINAL-IMPLEMENTATION-PLAN-COMPLETE.md Phases 6-10
✅ What Works Now (Confirmed)
Based on database analysis:
- ✅ 5 plans configured and active
- ✅ Account → Plan relationship working
- ✅ User → Account relationship working
- ✅ Site → Account tenancy isolation working
- ✅ Credit tracking (280+ transactions logged)
- ✅ Credit deduction before AI calls
- ✅ Role-based permissions enforced
- ✅ Middleware account injection working
❌ What Needs Fixing (Confirmed)
High Priority
- ❌ Payment method fields (don't exist in DB)
- ❌ Superuser session contamination (security issue)
- ❌ Registration credit seeding (gives 0 credits currently)
- ❌ API key bypasses account validation
Medium Priority
- ❌ Subscription date accuracy (not enforced)
- ❌ Docker build caching (causes router errors)
- ❌ Throttling too permissive (all users bypass)
- ❌ Bank transfer endpoint (doesn't exist)
Low Priority
- ❌ System account logic unclear
- ❌ Test coverage gaps
📖 Reading Order
If you need to understand the system:
- Start: CURRENT-STATE-CONTEXT.md (what exists now)
- Then: FINAL-IMPLEMENTATION-REQUIREMENTS.md (what must be fixed)
- Finally: FINAL-IMPLEMENTATION-PLAN-COMPLETE.md (how to fix it)
If you need to implement:
- Read: FINAL-IMPLEMENTATION-REQUIREMENTS.md (all constraints)
- Follow: FINAL-IMPLEMENTATION-PLAN-COMPLETE.md (step-by-step)
- Reference: CURRENT-STATE-CONTEXT.md (what's in database)
🎓 Key Learnings from Analysis
About Database
- System is actively used (280+ credit transactions)
- No subscriptions exist (payment system not wired)
- All relationships working correctly
- Migration 0006 is latest (soft delete)
About Code
- Credit system fully functional
- Middleware validates accounts
- Permissions enforce tenancy
- Registration needs credit seeding
About Critical Issues
- Superuser contamination is REAL risk
- Docker caching causes real errors (not code bugs)
- Subscription dates must be precise
- Plan allocation must be strict
💡 Implementation Strategy
Conservative Approach (Recommended)
- Fix critical security issues first (Day 1)
- Superuser isolation
- Docker build stability
- Add payment infrastructure (Day 2-3)
- Migrations
- Endpoints
- Add validation and enforcement (Day 4-5)
- API key
- Throttling
- Test everything (Day 6)
- Deploy carefully (Day 7)
Aggressive Approach (If Confident)
- All migrations first
- All code changes together
- Test and deploy
Recommendation: Conservative approach with rollback ready
🔒 Security Checklist
Before going live:
- Superuser contamination fixed
- API key validates account status
- Session auth disabled for /api/*
- Throttling enforced per account
- Credits seeded on registration
- Subscription dates accurate
- No authentication bypasses
- All tests passing
📞 Support Information
Files to reference:
- Database state:
CURRENT-STATE-CONTEXT.md - Requirements:
FINAL-IMPLEMENTATION-REQUIREMENTS.md - Implementation:
FINAL-IMPLEMENTATION-PLAN-COMPLETE.md
Query script:
backend/check_current_state.py- Rerun anytime to check DB
Rollback:
- All migration + code rollback steps in FINAL-IMPLEMENTATION-REQUIREMENTS.md
✨ Final Note
This folder now contains:
- ✅ Complete database context from production
- ✅ All gaps identified with exact file references
- ✅ All 4 critical issues documented
- ✅ Step-by-step implementation plan
- ✅ Code changes ready (3 files modified)
- ✅ Verification tests specified
- ✅ Rollback strategies defined
When you're ready to implement, everything you need is here.
No guesswork. No assumptions. 100% accurate.
Start implementation by reading FINAL-IMPLEMENTATION-REQUIREMENTS.md and following FINAL-IMPLEMENTATION-PLAN-COMPLETE.md