HoopAI Docs — Information Architecture Restructure
Design principles
- Mirror the platform sidebar — the docs nav should match what users see when they log in
- Each module = its own section — no more “Modules” mega-tab
- Quick wins for Getting Started — just the essentials to get productive
- Split mega-modules — Sites, Payments need breaking up
- Promote standalone features — Forms, Surveys, QR Codes, Reputation deserve their own space
- Order matches the platform — top-to-bottom matches the sidebar screenshot
- Every existing URL keeps working — redirects for anything that moves
Current structure (problems)
Home
Getting Started ← overlaps with Academy, too much for onboarding
Setup (16 pages)
Guides (66 pages) ← these are really academy content
Modules ← MEGA-TAB with 17 menu items, 600+ pages
Mobile App | CRM | Sales | Calendars | Conversations | Marketing |
Automation | AI Agents | Learning & Community | Commerce |
Reporting & Dashboards | Settings | Sites | Store & Ecommerce |
Content | Forms & Surveys | Media Library
Developers
API Reference
CMS ← duplicates content from Modules > Sites
Resources ← Account & Billing, Troubleshooting, Legal
Problems:
- “Modules” has 17 menus — users can’t find anything
- Reputation is buried under Marketing > groups
- CMS tab duplicates Sites content
- Getting Started has 82 pages (not “getting started” anymore)
- Academy vs Guides vs Getting Started — 3 overlapping concepts
- Forms, Surveys, QR Codes buried under “Content” or “Sites”
- E-commerce (stores) vs Commerce (payments) is confusing naming
Proposed new structure
Home | Get Started | Mobile App | Dashboard | Conversations | Calendars |
CRM | Opportunities | Payments | AI Agents | Marketing | Automation |
Sites | Forms & Surveys | E-commerce | Memberships | Reputation |
Reporting | Settings | Resources | Developers | API Reference
That’s 21 tabs — too many for a tab bar. Here’s the optimized version that groups tightly related modules while keeping everything findable:
Recommended: 12 tabs
Home | Get Started | Conversations | Calendars | CRM |
Marketing | Automation & AI | Sites & Content | Commerce |
Reputation | Reporting | Settings | Resources | Developers
Why 12 tabs:
- Mintlify Sequoia scrolls tabs, but 12 fits well on desktop
- Each tab maps to 1-3 platform sidebar items (clear mental model)
- No more “Modules” catch-all
Detailed structure
Tab 1: Home
Single landing page with search, quick links, popular topics.
Tab 2: Get Started
Simplified to quick wins only. A new user should finish this in 30-60 minutes.
Menu: Quick Start
Group: First Steps
- Log in & navigate the platform
- Set up your business profile
- Invite your team
- Import your contacts
Group: Connect Your Channels
- Connect social media accounts
- Set up email (connect domain)
- Get a phone number (optional)
- Connect WhatsApp (optional)
- Add chat widget to your website
Group: Essential Setup
- Set up a calendar
- Create your first workflow
- Customize your dashboard
Menu: Migration
Group: Platform Migration Guides
- Migrate from Mailchimp
- Migrate from HubSpot
- Migrate from Salesforce
- Migrate from ActiveCampaign
- Migrate from ClickFunnels
- Migrate from Calendly
- Migrate from Kajabi
What happens to old Getting Started + Academy content?
- Detailed guides move INTO their respective module tabs (e.g., “email blast” guide → Marketing tab)
- Academy onboarding steps become the Quick Start above
- Academy recipes become examples/guides within each module tab
- The Academy tab is removed — no more confusion about where to go
Tab 3: Conversations
Matches platform sidebar: Conversations (+ its sub-tabs: Conversations, Manual Actions, Snippets, Trigger Links, Settings)
Menu: Conversations
Group: Overview
- Conversations overview
- Navigating the inbox
Group: Messaging
- Sending messages (SMS/email)
- Two-way SMS
- Scheduled messages
- Email threads
- Group chat
- RCS messaging
- Templates & snippets
Group: Calling
- Inbound call routing
- Missed call text back
- Call recording
- Call quality
- Call scripts
- Call dispositions
- Ringless voicemail
- Local presence dialing
- VoIP deskphones (link to Settings)
Group: WhatsApp
- WhatsApp overview
- WhatsApp messaging
- WhatsApp templates
- WhatsApp 24-hour window
- WhatsApp automation
- WhatsApp coexistence
- WhatsApp pricing
- WhatsApp troubleshooting
Group: Social Messaging
- Social messaging
- Comment automation (FB/IG)
Group: Conversation Management
- Assignment rules
- Labels & filters
- Bulk actions
- Internal comments
- Manual actions
- Unread management
- Do not disturb
- Trigger links
- Contact details panel
- Contact engagement score
- Requesting payment
Group: Settings
- Conversations settings
- SMS compliance
- Live chat setup
Menu: Phone System
Group: Phone Setup & Management
- Phone system explained
- Phone number management
- Phone number porting
- Phone system pricing
- Caller ID & CNAM verification
- A2P 10DLC registration
Group: Troubleshooting
- SMS error codes
- SMS delivery failures
- SMS troubleshooting
- Phone system issues
Tab 4: Calendars
Matches platform sidebar: Calendars (Calendar View, Appointment List View, Calendar Settings)
Menu: Calendars
Group: Overview
- Calendars overview
Group: Setup & Configuration
- Calendar types
- Calendar settings
- Availability hours
- Calendar integrations
- Widget customization
- Calendar groups
Group: Booking & Scheduling
- Booking pages
- Group booking
- Round-robin booking
- Collective booking
- Service calendars
- Class booking
- Payment calendars
- One-time booking links
- Google organic booking
- Appointment notes
Group: Appointments
- Managing appointments
- Appointment list view
- Notifications & reminders
- Rentals & listings
Group: Troubleshooting
- Calendar troubleshooting
Tab 5: CRM
Combines platform sidebar: Contacts + Opportunities (they’re the core data layer)
Menu: Contacts
Group: Overview
- Contacts overview
- Contact types
Group: Managing Contacts
- Contact details
- Custom fields
- Multiple phone numbers
- Multiple email addresses
- Notes
- Contact activity timeline
- Associations
- Followers
- Do not contact
Group: Organizing & Segmenting
- Smart lists
- Tags
- Filters & saved views
- Contact scoring & lead scoring
Group: Import & Export
- Importing contacts
- CSV import format guide
- Bulk import troubleshooting
- Exporting contacts
- Restore deleted contacts
Group: Bulk Operations
- Bulk actions
- Duplicate management
- Data quality
Group: Tasks
- Tasks overview
Group: Privacy & Compliance
- GDPR consent tracking
- AI enrichment
Menu: Companies
Group: Companies
- Companies overview (businesses.mdx)
Menu: Opportunities & Pipelines
Group: Overview
- Opportunities overview
Group: Pipeline Management
- Pipelines
- Pipeline stages
- Kanban board
- List view
Group: Managing Opportunities
- Opportunity details
- Opportunity value
- Custom fields
- Notes
- Bulk actions
- Followers
- Lost reasons
- Managing opportunities
Group: Sales Tools
- Playbooks (NEW)
- Forecasting (NEW)
- Sales sequences (NEW)
Group: Automation & Reporting
- Automation triggers
- Opportunity reporting
Tab 6: Marketing
Matches platform sidebar: Marketing (Social Planner, Emails, Snippets, Countdown Timers, Trigger Links, Affiliate Manager, Brand Boards, Ad Manager)
Menu: Email Marketing
Group: Getting Started
- Email marketing overview
- Email builder
- Email templates
- Email personalization
Group: Campaigns & Automation
- Email campaigns
- Email automation
- Email A/B testing
- Email AI scheduling
- Email RSS
- Countdown timers
- Trigger links
Group: Deliverability
- Email deliverability guide
- Dedicated email domain
- Mailgun setup
- Mailgun registrar guides
- Email DMARC
- Email warm-up
- Google Postmaster
- Email sender requirements
- Email bounce management
- Email suppression
Group: Compliance & Analytics
- Email compliance
- Email list management
- Email analytics
- Email error codes
Group: Advanced
- SMTP setup
- Email services (settings)
- Email signatures
- Email deliverability settings
Menu: Social Media
Group: Social Planner
- Social media overview
- Social planner
- Social planner features
- Social planner platforms
- Social calendar
- Social categories & queues
Group: Publishing
- Social post types
- Social content specs
- Social AI writer
- Social CSV import
- Social approval workflow
- Social TikTok
Group: Engagement
- Social comment management
- Social listening
Group: Analytics
- Social analytics
Menu: Ad Manager
Group: Advertising
- Ad manager overview
- Facebook ads
- Google ads
- LinkedIn ads
- Facebook CAPI (Meta Conversions API)
- Ad audiences
- Ads reporting
Menu: Affiliate Manager
Group: Affiliate Program
- Affiliate manager overview
- Affiliate campaigns
- Affiliate tracking
- Affiliate portal
- Affiliate payouts
- Affiliate automation
Menu: Brand & Content Tools
Group: Tools
- Brand boards
- Snippets
- Prospecting tool
Tab 7: Automation & AI
Combines platform sidebar: Automation + AI Agents (they’re deeply related)
Menu: Workflows
Group: Overview
- Workflows overview
- Workflow builder
- Advanced workflow builder
- Workflow AI builder
Group: Triggers & Actions
- Workflow triggers
- Triggers reference
- Workflow actions
- Actions reference
- Premium actions
Group: Logic & Flow
- If/else conditions
- Wait actions
- Goal events
- Enrollment settings
- Drip sequences
- SMS campaigns
Group: Integrations
- Custom webhooks
- Inbound webhooks
- Zapier integration
- Make integration
- Trigger links
Group: Management
- Workflow templates
- Workflow recipes
- Workflow folders
- Workflow history
- Workflow statistics
- Workflow troubleshooting
- Global workflow settings
Menu: AI Agents
Group: Getting Started
- AI overview
- Choosing the right AI
- AI quick start
- AI checklist
- AI pricing
- AI features matrix
- AI glossary
- AI models
Group: Agent Studio (NEW)
- Agent Studio overview
- Creating agents
- Agent templates
- Managing agents
Group: Conversation AI
- Conversation AI overview
- Bot setup
- Multi-bot
- Multi-channel
- Conversation AI actions
- Conversation AI dashboard
- Flow-based builder
- Train your bot
- Bot settings
Group: Voice AI
- Voice AI overview
- Creating voice agents
- Voice selection
- Inbound & outbound
- Outbound calling
- Phone setup
- Appointment booking
- Call escalation
- Website widget
- Testing & debugging
- Voice AI troubleshooting
Group: Content AI
- Content AI overview
- Email builder AI
- Page builder AI
- Social planner AI
Group: Workflow AI
- AI decision maker
- GPT actions
- Connecting bots to workflows
- Workflow AI examples
Group: Knowledge Base
- Knowledge base
- Ask AI
Group: Prompt Engineering
- Prompt engineering overview
- Advanced techniques
- Common mistakes
- Optimization
- Conversation AI prompts
- Voice AI prompts
Group: Use Cases & Templates
- Use cases overview
- Lead qualification bot
- Appointment scheduler
- AI receptionist
- After-hours support
- E-commerce support
- Real estate agent
- Multi-location
- Review automation
Group: Prompt Library
- Prompt library overview
- Customer support
- Sales qualification
- Appointment booking
- E-commerce
- Healthcare
- Real estate
- Agency/SaaS
- Voice AI templates
Group: Trust & Safety
- Trust overview
- Data privacy
- Security
- Compliance
- Guardrails
- Limitations
Group: Advanced
- Multi-language
- Cost optimization
- Performance
- API reference
- Migration
Tab 8: Sites & Content
Matches platform sidebar: Sites (Funnels, Websites, Blogs, Webinars, WordPress, Media Storage)
Forms, Surveys, Quizzes, Chat Widget, QR Codes pulled out into their own menus
Menu: Funnels
Group: Funnel Builder
- Funnels overview
- Funnel templates
- Funnel steps
- Funnel domains
- Funnel sharing
- Funnel analytics
Group: Funnel Features
- AI builder
- A/B testing
- Order forms
- Upsells & downsells
- Exit-intent popups
- Global sections
- Hosted video
- Custom code
- Tracking pixels
- Geo-fencing
Group: SEO & Performance
- SEO settings
- Schema markup
- Cookie consent
- Page speed optimization
- Funnel redirects
Group: Troubleshooting
- Funnel & website issues
Menu: Websites
Group: Website Builder
- Websites overview
- Multi-page navigation
- Blog integration
- Popup widgets
Menu: Blogs
Group: Blogging
- Blog overview
- Creating posts
- Blog templates
- Blog settings
- Importing posts
- Blog categories & tags
- Blog analytics
Menu: Forms & Surveys
Group: Forms
- Forms overview
- Building forms
- Form fields
- Conditional logic
- Multi-step forms
- Payment forms
- E-signature forms
- File uploads
- Math calculations
- Embedding forms
- Form styling
- Form settings
- Form notifications
- Form submission actions
- Form analytics
- Spam protection
- Importing submissions
Group: Surveys
- Surveys overview
- NPS surveys (NEW)
- CSAT surveys (NEW)
- Survey templates (NEW)
- Survey analytics (NEW)
Group: Quizzes
- Quizzes overview
Menu: Chat Widget
Group: Live Chat
- Chat widget overview
- Installation
- Platform guides
- Chat settings
Menu: QR Codes
Group: QR Code Builder
- QR codes overview
(existing QR code pages)
Menu: Media Library
Group: Media & Storage
- Media storage overview
(existing media pages)
Menu: Webinars
Group: Webinars
- Webinars overview
(existing pages)
Menu: WordPress
Group: WordPress Integration
- WordPress overview
(existing pages)
Tab 9: Commerce
Combines platform sidebar: Payments + Stores + Memberships (all money/product related)
Split into 3 clear menus:
Menu: Payments & Invoicing
Group: Overview
- Payments overview
Group: Invoices & Estimates
- Invoices
- Estimates
- Recurring invoices
- Invoice reminders
Group: Payment Collection
- Payment links
- Text to pay
- Payment plans
- Manual payments
- Apple Pay & Google Pay
- Buy now pay later
- Bank transfers (ACH/SEPA)
Group: Subscriptions
- Subscriptions
Group: Documents & Contracts
- Documents & contracts
- E-signatures
Group: Orders & Transactions
- Orders
- Transactions
- Refunds
- Import/export
Group: Products
- Products catalog
- Coupons
- Gift cards
- Taxes
Group: Payment Setup
- Payment settings
- Default gateways
- Payment integrations
- PayPal integration
- NMI integration
- Stripe (via integrations)
- Processing charges
- Checkout themes
- Accounting integrations
Menu: Online Stores (E-commerce)
Group: Store Setup
- Store overview
(all stores/* pages)
Group: Shipping & Fulfillment
- Shipping integrations
- Printful integration
- Dropshipping
Group: Social Commerce
- Facebook & Instagram shops
Group: Shopify & Imports
- Shopify integration
Menu: Memberships & Courses
Group: Overview
- Memberships overview
Group: Client Portal
- Client portal overview
- Portal setup
- Portal features
- Custom domain
Group: Courses
- Course creation
- Course pricing
- Course import (Skool, Kajabi)
- Course assessments
Group: Communities
- Communities overview
- Community groups
- Go Live
- Community events
- Community newsletters
- Credentials
Group: Mobile App (White-label)
- Branded mobile app (PWA)
- Membership access
Tab 10: Reputation
Matches platform sidebar: Reputation (Overview, Requests, Reviews, Video Testimonials, Widgets, Listings, Settings, GBP Optimization)
Promoted to its own tab — no longer buried under Marketing.
Menu: Reputation
Group: Overview
- Reputation overview
- Reputation tab overview
Group: Reviews
- Reviews overview
- Google review integration
- Facebook review integration
- Add reviews manually
- Negative review handling
- Review response templates
- Reviews AI agent
Group: Review Requests
- Sending review requests
- Review email templates
- Review automation
- Review QR code
Group: Widgets & Showcase
- Review website widget
- Review widget customization
- Review showcase
- Video testimonials
Group: Listings & GBP
- Listings overview
- Listing sync
- GBP optimization
- GBP posts
- Competitor tracking
Group: Analytics & Settings
- Review reporting
- Reputation settings
Tab 11: Reporting
Matches platform sidebar: Reporting + Dashboard
Menu: Dashboards
Group: Dashboard Basics
- Dashboard overview
- Managing dashboards
- Dashboard templates
- Dashboard sharing
- Dashboard permissions
- Exporting dashboards
Group: Widgets
- Dashboard elements
- Custom widgets
- Appointment widget
- Conversation widget
- Email widget
- Funnel widget
- Google Analytics widget
- Payments widget
- Reputation widget
- Revenue widget
- Sales efficiency widget
- Visitor data widget
Group: Configuration
- Dashboard theme
- Date range filters
- Quick filters
- Goal tracking
Menu: Reports
Group: Overview
- Reporting overview
- Custom reports
- Report scheduling
- Marketing audit reports
Group: Communication Reports
- Email reporting
- SMS reporting
- Call reporting
Group: Marketing Reports
- Attribution reporting
- Ads reporting
- Facebook pixel reporting
- Social media reporting
- Conversion reporting
- Google Analytics integration
Group: Sales & Revenue
- Revenue reporting
- Agent reporting
- Funnel reports
- Appointment report
- Contact growth report
Group: Workflow Reports
- Workflow reporting
- Audit reports
Tab 12: Settings
Matches platform sidebar: Settings (all items from the screenshot)
Menu: Account
Group: Account Basics
- Settings overview
- Business profile
- My profile
- My staff (users & roles)
- Teams & permissions (NEW)
- Permission sets (NEW)
Group: Security
- SSO/SAML
- Security checklist
- Audit logs
- Trust center
Menu: Communication Setup
Group: Phone System
- Phone system overview
- Phone number management
- Phone number porting
- Phone system pricing
- Caller ID & CNAM
- A2P 10DLC
- VoIP deskphones
Group: Email Services
- Email services
- Email deliverability settings
- Email signatures
- Dedicated email domain
Group: WhatsApp
- WhatsApp setup
Group: Notifications
- Notification settings
Menu: Data & Customization
Group: Objects & Fields
- Custom objects
- Custom fields
- Custom values
- Tags
Group: Scoring
- Manage scoring
Group: Domains
- Domains & URL redirects
- External tracking
Menu: Integrations
Group: Integration Hub
- Integrations overview
- Private integrations
- Webhooks
- Facebook integration
- QuickBooks integration
- Xero integration
- TikTok integration
Group: Platform
- Plan comparison
- Platform limits
- Labs
- SaaS mode
Menu: Billing & Subscription
Group: Your Account
- Billing portal
- Usage & add-ons
- Payment issues
- Plan comparison
- Cancel or downgrade
- Data export
Tab 13: Resources
Menu: Troubleshooting
Group: General
- FAQ
- Login issues
- Password reset
- Account locked
- Clear browser cache
- Screen loading issues
- Page won't load
Group: Communication
- SMS error codes
- SMS delivery failures
- SMS forwarding issues
- Email error codes
- Email metrics
- Phone system issues
- Audio issues
- Bad call quality
Group: Websites & Funnels
- Funnel & website issues
- Domains troubleshooting
- Instant redirect pages
- Custom URL redirects
Group: Workflows & Data
- Workflow troubleshooting
- If/else troubleshooting
- Race conditions
- Loop lockouts
- Bulk import issues
- Sticky contacts
Group: Integrations
- Facebook lead ads
- Facebook publishing
- Google ads reporting
- Google Business Profile publishing
- WordPress issues
- SMTP providers
Group: Calendar
- Calendar issues
Menu: Mobile App
Group: Getting Started
- Mobile app overview
- (existing mobile app pages)
Group: Features
- (existing pages)
Menu: Legal
Group: Policies
- Terms of service
- Privacy policy
- Data processing agreement
- Product terms
- Acceptable use
Group: Data & Security
- HIPAA compliance
- GDPR
Tab 14: Developers
Menu: Developer Guides
Group: Getting Started
- Developer introduction
- Quick start
- Authentication
- Making requests
Group: Guides
- Best practices
- SDKs & tools
- Webhooks
- Marketplace apps
Group: AI & MCP
- MCP overview
- MCP quickstart
- Platform MCP server
- HoopAI proxy
- Subagents
Menu: API Reference
(keep existing API reference structure)
What gets killed / merged
| Current | New Location | Action |
|---|
| ”Modules” mega-tab | Split across tabs 3-12 | KILLED |
| CMS tab | Merged into Sites & Content | KILLED |
| Academy tab content | Distributed into module tabs | KILLED |
| Getting Started > Guides (66 pages) | Quick recipes → module tabs | MOVED |
| Getting Started > Academy recipes | Become examples within modules | MOVED |
| ”Learning & Community” menu | → Commerce > Memberships & Courses | RENAMED |
| ”Store & Ecommerce” menu | → Commerce > Online Stores | RENAMED |
| ”Content” menu (blogs, QR, chat) | → Sites & Content (separate menus) | SPLIT |
| ”Forms & Surveys” menu | → Sites & Content > Forms & Surveys | PROMOTED |
| ”Media Library” menu | → Sites & Content > Media Library | MOVED |
| Reputation (under Marketing groups) | → Own tab | PROMOTED |
| Mobile App (under Modules) | → Resources > Mobile App | MOVED |
Getting Started: before vs after
Before (82 pages!)
- Setup: Welcome (8), Core Setup (5), Account Management (3)
- Guides: Onboarding (12), Quick Start (11), SMS (7), Email (4), Workflows (7), Funnels (7), Calendars (5), Media (4), Payments (4), Migration (7)
After (19 pages)
- Quick Start: First Steps (4), Connect Channels (5), Essential Setup (3)
- Migration: Platform guides (7)
63 pages moved into their respective module tabs as “getting started” or “how-to” content within that module.
Order rationale
The tab order follows the platform sidebar with one adjustment:
Platform sidebar: Docs tabs:
Launchpad → Home
Dashboard → (in Reporting tab)
Conversations → Conversations
Calendars → Calendars
Contacts → CRM (contacts + opportunities combined)
Opportunities → (in CRM tab)
Payments → Commerce (payments + stores + memberships)
AI Agents → Automation & AI (workflows + AI combined)
Marketing → Marketing
Automation → (in Automation & AI tab)
Sites → Sites & Content
Memberships → (in Commerce tab)
Media Storage → (in Sites & Content tab)
Reputation → Reputation
Reporting → Reporting
Settings → Settings
Mobile App goes under Resources since it’s not a sidebar module — it’s a companion app.
Redirect map (high-level)
Every directory that moves needs a redirect in docs.json:
"redirects": [
{ "source": "/academy/:path*", "destination": "/<module>/:path*" },
{ "source": "/sites/:path*", "destination": "/sites-content/:path*" },
{ "source": "/stores/:path*", "destination": "/commerce/stores/:path*" },
{ "source": "/memberships-and-communities/:path*", "destination": "/commerce/memberships/:path*" },
{ "source": "/reputation/:path*", "destination": "/reputation/:path*" },
...
]
Actual redirect mapping will be done file-by-file during execution.
New gap pages to create during restructure
While restructuring, these NEW pages should be created to fill remaining gaps:
ai-agents/agent-studio.mdx — Agent Studio overview (from screenshot)
opportunities/playbooks.mdx — Sales playbooks
opportunities/forecasting.mdx — Sales forecasting
opportunities/sales-sequences.mdx — Sales sequences
surveys/nps-surveys.mdx — NPS survey setup
surveys/csat-surveys.mdx — CSAT survey setup
surveys/survey-templates.mdx — Survey template library
surveys/survey-analytics.mdx — Survey analytics
contacts/data-quality.mdx — Data quality & cleanup
settings/teams-permissions.mdx — Teams & partitioning
settings/permission-sets.mdx — Permission sets
settings/record-layouts.mdx — Record layout customization
Execution phases
Phase 1: Structure (docs.json only)
- Rewrite docs.json navigation to new tab/menu/group structure
- Point all pages to their current file paths (no file moves yet)
- Add redirects for any URL changes
- Verify with mintlify dev
Phase 2: Content moves
- Move academy/guide pages into module directories
- Rename directories if needed
- Update all internal links
- Run mintlify broken-links
Phase 3: Gap fill
- Create the 12 new pages listed above
- Expand thin pages identified in gap analysis v2
Phase 4: Verify
- Playwright verification of every tab
- Broken link check
- Screenshot every section
Last modified on March 6, 2026