EXPLORATION_INDEX.md

PropertyWebBuilder Multi-Tenancy Exploration - Complete Documentation Index\n\nDate: January 7, 2026 \nScope: Complete multi-tenancy architecture exploration \nStatus: COMPLETE\n\n---\n\n## Documents Created\n\nThis exploration has created four comprehensive reference documents:\n\n### 1. MULTI_TENANCY_EXPLORATION_SUMMARY.md\n\nPurpose: Deep technical reference with complete architectural details\n\nContents:\n- Executive summary of multi-tenancy implementation\n- 14 detailed sections covering all aspects:\n 1. Tenant identification mechanism (subdomain, custom domain, slug)\n 2. Database configuration & connection patterns\n 3. Subdomain handling for tenant identification\n 4. Website/tenant creation & configuration\n 5. Seeding system & seed packs structure\n 6. Database schema & multi-tenancy columns\n 7. Controller architecture & tenancy\n 8. Acts_as_tenant configuration\n 9. Routing configuration\n 10. Environment variables & configuration\n 11. Security & data isolation\n 12. Data model relationships\n 13. Documentation files reference\n 14. Summary & quick reference table\n\nBest For:\n- Understanding complete architecture\n- Deep dives into specific components\n- Decision-making on multi-tenancy issues\n- Architectural documentation\n- Complete reference for developers\n\nRead This When:\n- You need to understand WHY something works\n- You're debugging complex multi-tenancy issues\n- You're making architectural changes\n- You need complete technical reference\n\n---\n\n### 2. MULTI_TENANCY_QUICK_START.md\n\nPurpose: Practical quick-reference guide for developers\n\nContents:\n- 60-second overview of tenancy\n- Key concepts explained simply\n- Common tasks with code examples:\n - List records for current website\n - Find one record safely\n - Create new records\n - Admin viewing all websites\n- Three controller types explained with examples\n- Domain types (subdomain vs custom domain)\n- Models you'll use most\n- Testing tenant isolation\n- Debugging checklist\n- Anti-patterns to avoid (with examples)\n- Creating new websites\n- Key files to know\n- Environment variables summary\n- TL;DR section\n\nBest For:\n- Quick lookups while coding\n- Understanding patterns\n- Avoiding common mistakes\n- Code examples and snippets\n- Onboarding new developers\n\nRead This When:\n- You're writing code\n- You need a quick reference\n- You want practical examples\n- You're not sure about a pattern\n- You're learning the codebase\n\n---\n\n### 3. MULTI_TENANCY_DATABASE_REFERENCE.md\n\nPurpose: Complete database architecture and schema reference\n\nContents:\n- Database configuration overview\n- Sharding implementation details\n- How automatic shard routing works\n- Schema synchronization strategy\n- Table schema patterns (with real SQL examples)\n- Querying with sharding\n- Migration workflow\n- Scaling scenarios (early, growth, enterprise)\n- Database maintenance (backup, monitoring, rebalancing)\n- Performance considerations\n- Troubleshooting guide\n\nBest For:\n- Understanding database structure\n- Implementing sharding\n- Writing migrations\n- Database optimization\n- Understanding schema patterns\n- DBA/operations team\n\nRead This When:\n- You need to write migrations\n- You're dealing with database issues\n- You want to understand sharding\n- You're optimizing queries\n- You're planning database operations\n\n---\n\n### 4. Existing Documentation (Already in Repo)\n\nThe repository also contains comprehensive documentation:\n\nLocation: /docs/multi_tenancy/\n\nKey Files:\n- README.md - Navigation and orientation guide\n- MULTI_TENANCY_ARCHITECTURE.md - Architecture diagrams and flows\n- routing_implementation.md - Technical implementation details\n- routing_architecture.md - Visual diagrams\n- multi_tenancy_guide.md - Developer best practices guide\n- MULTI_TENANCY_QUICK_REFERENCE.md - Quick lookup reference\n- DEVELOPER_GUIDE.md - Development best practices\n- MULTI_TENANCY_SECURITY_AUDIT.md - Security analysis\n\nThese are essential reading - created during project development.\n\n---\n\n## Quick Navigation by Use Case\n\n### I'm New to This Project\n\n1. Start: /docs/multi_tenancy/README.md - Orientation\n2. Read: MULTI_TENANCY_QUICK_START.md - Key concepts (THIS REPO)\n3. Deep dive: MULTI_TENANCY_EXPLORATION_SUMMARY.md (THIS REPO)\n4. Reference: /docs/multi_tenancy/multi_tenancy_guide.md - Patterns\n\n### I'm Writing a Controller\n\n1. Quick: MULTI_TENANCY_QUICK_START.md - Common tasks section\n2. Reference: /docs/multi_tenancy/multi_tenancy_guide.md - Controller patterns\n3. Deep: /docs/multi_tenancy/routing_implementation.md - Technical details\n\n### I'm Writing a Model\n\n1. Quick: MULTI_TENANCY_QUICK_START.md - Models section\n2. Guide: /docs/multi_tenancy/multi_tenancy_guide.md - Model patterns\n3. Reference: MULTI_TENANCY_EXPLORATION_SUMMARY.md - Section 12\n\n### I'm Writing Queries\n\n1. Quick: MULTI_TENANCY_QUICK_START.md - Common tasks\n2. Patterns: /docs/multi_tenancy/MULTI_TENANCY_QUICK_REFERENCE.md\n3. Anti-patterns: MULTI_TENANCY_QUICK_START.md - Avoid section\n\n### I'm Working on Database/Schema\n\n1. Start: MULTI_TENANCY_DATABASE_REFERENCE.md (THIS REPO)\n2. Reference: MULTI_TENANCY_EXPLORATION_SUMMARY.md - Section 6\n3. Examples: /docs/multi_tenancy/routing_implementation.md\n\n### I'm Debugging a Tenancy Issue\n\n1. Checklist: MULTI_TENANCY_QUICK_START.md - Debugging section\n2. Anti-patterns: MULTI_TENANCY_QUICK_START.md - What NOT to do\n3. Security: /docs/multi_tenancy/MULTI_TENANCY_SECURITY_AUDIT.md\n4. Deep dive: MULTI_TENANCY_EXPLORATION_SUMMARY.md - Section 11\n\n### I'm Implementing Sharding\n\n1. Overview: MULTI_TENANCY_DATABASE_REFERENCE.md - Sections 1-3\n2. Migration: MULTI_TENANCY_DATABASE_REFERENCE.md - Sections 6-7\n3. Examples: MULTI_TENANCY_DATABASE_REFERENCE.md - Section 8\n4. Troubleshooting: MULTI_TENANCY_DATABASE_REFERENCE.md - Section 10\n\n### I'm Onboarding a New Team Member\n\n1. Start: /docs/multi_tenancy/README.md\n2. Concepts: MULTI_TENANCY_QUICK_START.md\n3. Deep understanding: MULTI_TENANCY_EXPLORATION_SUMMARY.md\n4. Code examples: /docs/multi_tenancy/multi_tenancy_guide.md\n5. Reference: MULTI_TENANCY_QUICK_START.md - Key files section\n\n---\n\n## Key Findings Summary\n\n### Architecture Type\nSubdomain-Based Multi-Tenancy with Single Shared Database\n\n### Tenant Identification\n- Primary: Unique subdomain (e.g., myagency.propertywebbuilder.com)\n- Secondary: Custom domain (e.g., www.myrealestate.com)\n- API: X-Website-Slug header\n\n### Database Strategy\n- Single PostgreSQL database (pwb_production)\n- Optional secondary database for sharding (pwb_production_shard_1)\n- Row-level isolation via website_id foreign keys\n- Unique indexes per website (website_id, slug)\n\n### Scoping Mechanism\n- Manual WHERE clauses (Pwb:: models)\n- Optional automatic scoping (PwbTenant:: models - configured but not adopted)\n- Acts-as-tenant gem for tenant context management\n\n### Controller Tiers\n1. Pwb::ApplicationController - Public site (no auth)\n2. SiteAdminController - Single website admin (auth + authorization)\n3. TenantAdminController - Cross-tenant admin (email whitelist)\n\n### Seeding System\n- Seed packs for quick website provisioning\n- Base pack with standard setup\n- Specialized packs (netherlands_urban, spain_luxury)\n- Supports inheritance between packs\n\n### Domain Support\n- Platform subdomains configured via PLATFORM_DOMAINS env var\n- Custom domains with optional DNS verification\n- Reserved subdomains protection\n- Wildcard subdomain routing\n\n### Authorization\n- Site level: Pwb::UserMembership (user role for specific website)\n- Platform level: TENANT_ADMIN_EMAILS environment variable\n- Bypass for development: BYPASS_ADMIN_AUTH=true\n\n### Sharding\n- Transparent via Rails 6 connects_to\n- Website.shard_name determines database\n- Migrations mirrored across shards\n- Unsharded is default (all in primary)\n\n---\n\n## Core Implementation Files\n\n### Models\n- /app/models/pwb/website.rb - Tenant model (root)\n- /app/models/pwb/current.rb - Thread-local context storage\n- /app/models/pwb_tenant/application_record.rb - Tenant-scoped base\n- /app/models/pwb/application_record.rb - Non-scoped base\n\n### Controllers\n- /app/controllers/pwb/application_controller.rb - Public base\n- /app/controllers/site_admin_controller.rb - Single-tenant admin base\n- /app/controllers/tenant_admin_controller.rb - Cross-tenant admin base\n\n### Concerns\n- /app/controllers/concerns/subdomain_tenant.rb - Subdomain routing\n- /app/models/concerns/pwb/website_domain_configurable.rb - Domain resolution\n\n### Configuration\n- /config/database.yml - Database connections\n- /config/initializers/acts_as_tenant.rb - Tenant gem config\n- /config/initializers/tenant_domains.rb - Domain routing config\n\n### Seeding\n- /db/seeds.rb - Main entry point\n- /lib/pwb/seed_pack.rb - Pack manager\n- /lib/pwb/seed_runner.rb - Enhanced seeder\n- /db/seeds/packs/ - Pack definitions\n\n---\n\n## Critical Patterns to Remember\n\n### Pattern 1: Always Scope Queries\nruby\n# ✅ DO THIS\nPwb::Page.where(website_id: current_website.id)\ncurrent_website.pages\n\n# ❌ NEVER THIS\nPwb::Page.all\nPwb::Page.find(id)\n\n\n### Pattern 2: Set Website on Create\nruby\n# ✅ DO THIS\nPwb::Page.create!(title: 'Home', website_id: current_website.id)\ncurrent_website.pages.create!(title: 'Home')\n\n# ❌ NEVER THIS\nPwb::Page.create!(title: 'Home') # website_id is nil!\n\n\n### Pattern 3: Only Use Unscoped in TenantAdmin\nruby\n# ✅ OK in TenantAdminController\nclass TenantAdmin::WebsitesController < TenantAdminController\n def index\n @websites = Pwb::Website.unscoped.all\n end\nend\n\n# ❌ NEVER in public/site admin\nclass Pwb::PagesController < Pwb::ApplicationController\n def index\n @pages = Pwb::Page.unscoped.all # SECURITY ISSUE!\n end\nend\n\n\n### Pattern 4: Check Current Website\nruby\n# ✅ DO THIS\nreturn unless current_website\ncurrent_website&.name # Safe nil handling\n\n# ❌ NEVER THIS\ncurrent_website.name # Errors if nil\n\n\n---\n\n## Recommended Reading Order\n\nFor Complete Understanding (4-6 hours):\n1. /docs/multi_tenancy/README.md (15 min)\n2. MULTI_TENANCY_QUICK_START.md (30 min)\n3. MULTI_TENANCY_EXPLORATION_SUMMARY.md (2 hours)\n4. /docs/multi_tenancy/multi_tenancy_guide.md (1 hour)\n5. /docs/multi_tenancy/routing_implementation.md (1 hour)\n\nFor Quick Reference (30 min):\n1. MULTI_TENANCY_QUICK_START.md (20 min)\n2. /docs/multi_tenancy/MULTI_TENANCY_QUICK_REFERENCE.md (10 min)\n\nFor Specific Topics:\n- Sharding: MULTI_TENANCY_DATABASE_REFERENCE.md\n- Controllers: /docs/multi_tenancy/routing_implementation.md\n- Models: /docs/multi_tenancy/multi_tenancy_guide.md\n- Security: /docs/multi_tenancy/MULTI_TENANCY_SECURITY_AUDIT.md\n- Patterns: /docs/multi_tenancy/MULTI_TENANCY_QUICK_REFERENCE.md\n\n---\n\n## Questions This Documentation Answers\n\n### Architecture Questions\n- What makes a website a "tenant"? (EXPLORATION_SUMMARY Section 1)\n- How does one domain map to one tenant? (EXPLORATION_SUMMARY Section 3)\n- How do multiple websites share one database? (EXPLORATION_SUMMARY Section 6)\n- Why not use ActiveRecord's acts-as-tenant fully? (EXPLORATION_SUMMARY Section 8)\n- How does sharding work? (DATABASE_REFERENCE Sections 1-3)\n\n### Coding Questions\n- How do I list records for current website? (QUICK_START Task 1)\n- How do I find a record safely? (QUICK_START Task 2)\n- How do I create a record? (QUICK_START Task 3)\n- Which controller do I use? (QUICK_START Controller Types)\n- What models are website-scoped? (QUICK_START Models section)\n\n### Database Questions\n- What columns do I need? (DATABASE_REFERENCE Section 4)\n- How do I write migrations? (DATABASE_REFERENCE Section 6)\n- How do I implement sharding? (DATABASE_REFERENCE Sections 1-3)\n- How do I scale from one database to two? (DATABASE_REFERENCE Section 8)\n- How do I move a tenant between shards? (DATABASE_REFERENCE Section 8)\n\n### Debugging Questions\n- Wrong data showing? (QUICK_START Debugging section)\n- Auth not working? (QUICK_START Debugging section)\n- Query going to wrong shard? (DATABASE_REFERENCE Section 10)\n- Schema out of sync? (DATABASE_REFERENCE Section 10)\n- Data not saved to right website? (QUICK_START Debugging section)\n\n### Security Questions\n- How is data isolated? (EXPLORATION_SUMMARY Section 11)\n- Can users see other websites' data? (EXPLORATION_SUMMARY Section 11)\n- What are common vulnerabilities? (EXPLORATION_SUMMARY Section 11)\n- How is admin access secured? (EXPLORATION_SUMMARY Section 7)\n\n---\n\n## Related Documentation\n\nExploration focused on multi-tenancy. For related topics, see:\n\n- Subscription System: /docs/multi_tenancy/SUBSCRIPTION_PLAN_SYSTEM.md\n- Seed Packs: /docs/seeding/ (if exists)\n- Field Keys System: /docs/field_keys/ (if exists)\n- Email Architecture: /docs/email/email_multi_tenant_architecture.md\n- Theme System: Check app/themes documentation\n- API/GraphQL: Deprecated, see /app/frontend/DEPRECATED.md\n\n---\n\n## File Locations\n\nExploration Documents (Created Today):\n- /MULTI_TENANCY_EXPLORATION_SUMMARY.md - Deep technical reference\n- /MULTI_TENANCY_QUICK_START.md - Practical quick guide\n- /MULTI_TENANCY_DATABASE_REFERENCE.md - Database architecture\n- /EXPLORATION_INDEX.md - This file\n\nExisting Documentation:\n- /docs/multi_tenancy/README.md - Start here\n- /docs/multi_tenancy/MULTI_TENANCY_ARCHITECTURE.md - Architecture diagrams\n- /docs/multi_tenancy/multi_tenancy_guide.md - Developer guide\n- /docs/multi_tenancy/MULTI_TENANCY_QUICK_REFERENCE.md - Quick reference\n- /docs/multi_tenancy/routing_implementation.md - Technical details\n\nSource Code:\n- /app/models/pwb/website.rb - Tenant root model\n- /app/controllers/concerns/subdomain_tenant.rb - Routing logic\n- /config/database.yml - Database configuration\n- /config/initializers/ - Configuration files\n\n---\n\n## Exploration Complete\n\nThis exploration has comprehensively documented PropertyWebBuilder's multi-tenancy architecture:\n\n✓ Tenant identification mechanisms \n✓ Database configuration and sharding \n✓ Subdomain and custom domain handling \n✓ Website creation and seeding \n✓ Controller architecture and authorization \n✓ Query scoping and data isolation \n✓ Security considerations \n✓ Performance patterns \n✓ Debugging strategies \n✓ Migration workflows \n\nThe three new documents provide:\n- Deep reference for architects and advanced developers\n- Quick practical guide for day-to-day coding\n- Database architecture guide for schema work\n\nCombined with existing documentation, there is now comprehensive coverage of the entire multi-tenancy system.\n"}