<project_specification>
  <project_name>MSP Quote Wizard</project_name>

  <overview>
    An interactive quotation wizard embedded on azcomputerguru.com that guides prospects through MSP service selection, generates proposals with pricing, and syncs leads to SyncroRMM. Features a 7-step linear wizard with expandable educational content, real-time price calculations, and admin dashboard for lead management.
  </overview>

  <technology_stack>
    <frontend>
      <framework>React 19 + TypeScript</framework>
      <build_tool>Vite</build_tool>
      <styling>Tailwind CSS v4 (GuruRMM glassmorphism design system)</styling>
      <state_management>React Context + useReducer</state_management>
      <api_client>Axios + React Query</api_client>
      <animations>Framer Motion</animations>
      <icons>Lucide React</icons>
    </frontend>
    <backend>
      <runtime>Python 3.11+ (FastAPI)</runtime>
      <database>MariaDB 10.6</database>
      <orm>SQLAlchemy</orm>
      <api_host>172.16.3.30:8001 (extend existing ClaudeTools API)</api_host>
    </backend>
    <communication>
      <api>RESTful JSON API</api>
      <auth>JWT for admin endpoints, token-based for public quote access</auth>
    </communication>
    <integrations>
      <crm>SyncroRMM API (https://computerguru.syncromsp.com/api/v1)</crm>
      <email>SMTP or SendGrid for notifications</email>
      <pdf>WeasyPrint or Puppeteer for quote generation</pdf>
    </integrations>
  </technology_stack>

  <prerequisites>
    <environment_setup>
      - Node.js 20+ for frontend development
      - Python 3.11+ for backend
      - Access to MariaDB at 172.16.3.30:3306
      - SyncroRMM API credentials
      - SMTP credentials for email notifications
    </environment_setup>
  </prerequisites>

  <feature_count>141</feature_count>

  <security_and_access_control>
    <user_roles>
      <role name="public">
        <permissions>
          - Can create and view their own quotes via access token
          - Can submit quotes with contact information
          - Can view/download PDF of their quote
          - Cannot access admin endpoints
        </permissions>
        <protected_routes>
          - /api/quotes/* (public with token)
        </protected_routes>
      </role>
      <role name="admin">
        <permissions>
          - Can view all quotes
          - Can update quote status
          - Can view analytics/stats
          - Can manually sync to SyncroRMM
          - Can configure notification settings
        </permissions>
        <protected_routes>
          - /api/admin/* (JWT required)
          - /admin/* pages in GuruRMM dashboard
        </protected_routes>
      </role>
    </user_roles>
    <authentication>
      <method>Token-based for public quotes, JWT for admin</method>
      <session_timeout>24 hours for quote tokens, standard JWT for admin</session_timeout>
      <quote_expiry>30 days after creation</quote_expiry>
    </authentication>
    <sensitive_operations>
      - Quote submission triggers SyncroRMM sync
      - Admin status changes are logged
      - Email/phone validation before sync
    </sensitive_operations>
    <seo>
      - noindex, nofollow meta tags on quote wizard
      - X-Robots-Tag header on hosting server
    </seo>
  </security_and_access_control>

  <core_features>
    <wizard_navigation>
      - Progress bar showing current step and completion
      - Step indicators with clickable navigation (for completed steps)
      - Next/Back buttons with validation
      - Step transition animations
      - Auto-save draft on step change
      - Resume incomplete quote via token
      - Mobile-responsive step layout
    </wizard_navigation>

    <step_1_company_profile>
      - Company name input (optional)
      - Number of endpoints/employees input
      - Industry dropdown selection
      - "What brings you here today?" textarea (optional)
      - Form validation with helpful messages
      - Auto-create quote draft on entry
    </step_1_company_profile>

    <step_2_gps_monitoring>
      - Three tier pricing cards (Basic $19, Pro $26, Advanced $39)
      - Expandable feature descriptions for each tier
      - Quantity input tied to endpoint count from Step 1
      - Equipment monitoring add-on toggle ($25/mo base + $3/device)
      - Real-time price calculation display
      - Tier comparison table (expandable)
      - Recommended tier highlight based on company size
    </step_2_gps_monitoring>

    <step_3_support_plan>
      - Four tier pricing cards (Essential $200, Standard $380, Premium $540, Priority $850)
      - Included hours and response time display
      - Effective hourly rate calculation
      - Prepaid block time option (10hr/$1500, 20hr/$2600, 30hr/$3000)
      - Expandable details for each tier
      - Recommendation based on endpoint count
    </step_3_support_plan>

    <step_4_voip>
      - Toggle: "Need business phones?"
      - Skip step if toggle is off
      - Four VoIP tier cards (Basic $22, Standard $28, Pro $35, CallCenter $55)
      - User count input
      - Hardware options with quantity selectors
        - Basic Desk Phone (T53W) $219
        - Business Desk Phone (T54W) $279
        - Executive Phone (T57W) $359
        - Conference Phone (CP920) $599
        - Wireless Headset (WH62) $159
        - Cordless Phone (W73P) $199
      - Add-on services (DID, toll-free, SMS, fax, Teams)
      - Real-time total calculation
    </step_4_voip>

    <step_5_web_email>
      - Web hosting toggle with tier selection
        - Starter $15 (5GB, 1 site)
        - Business $35 (25GB, 5 sites)
        - Commerce $65 (50GB, unlimited)
      - Email provider choice (expandable comparison)
        - WHM Email ($2-20/mailbox based on storage)
        - Microsoft 365 Basic $7, Standard $14, Premium $24
        - Exchange Online $5
      - Email user count input
      - Add-ons: email security $3/mailbox, dedicated IP $5, SSL $6.25
    </step_5_web_email>

    <step_6_summary>
      - Itemized breakdown by category
      - Monthly recurring total (prominent display)
      - One-time/setup costs (separate section)
      - Edit buttons to revisit any step
      - Collapsible category sections
      - Savings highlight if applicable
      - Print-friendly view option
    </step_6_summary>

    <step_7_contact>
      - Contact name (required)
      - Email address (required, validated)
      - Phone number (recommended, formatted)
      - Company name (pre-filled from Step 1)
      - Current IT situation textarea
      - Preferred contact method selection
      - Terms acceptance checkbox
      - Submit button with loading state
      - Duplicate email check against SyncroRMM
      - Success confirmation with quote reference
    </step_7_contact>

    <expandable_info>
      - Collapsible info cards throughout wizard
      - "Learn more" buttons for each feature
      - Smooth expand/collapse animations
      - Feature definitions in plain language
      - Use case examples
      - Comparison tables within expandables
    </expandable_info>

    <pricing_calculations>
      - Real-time total updates as selections change
      - Category subtotals
      - One-time vs recurring separation
      - Quantity-based calculations
      - Add-on aggregation
      - Discount display (if applicable)
    </pricing_calculations>

    <quote_api_public>
      - POST /api/quotes - Create new quote (returns access_token)
      - GET /api/quotes/{token} - Get quote by access token
      - PUT /api/quotes/{token} - Update quote (wizard progress)
      - POST /api/quotes/{token}/submit - Finalize and submit
      - GET /api/quotes/{token}/pdf - Generate PDF
      - Rate limiting for public endpoints
    </quote_api_public>

    <quote_api_admin>
      - GET /api/admin/quotes - List all quotes (paginated, filterable)
      - GET /api/admin/quotes/{id} - Get quote details
      - PUT /api/admin/quotes/{id} - Update status, add notes
      - GET /api/admin/quotes/stats - Dashboard analytics
      - POST /api/admin/quotes/{id}/sync-syncro - Manual sync
    </quote_api_admin>

    <syncro_integration>
      - Duplicate check via GET /customers?email={email}
      - Lead creation via POST /leads
      - Quote details in ticket_description
      - Sync status tracking
      - Error handling for API failures
      - Manual retry capability
    </syncro_integration>

    <notifications>
      - Customer confirmation email with quote link
      - Admin alert email on new submission
      - Email templates with branding
      - Quote PDF attachment option
      - Webhook support for automation
    </notifications>

    <admin_dashboard>
      - Quote listing with filters (status, date, value)
      - Search by company/contact/email
      - Quote detail view with full breakdown
      - Activity timeline per quote
      - Status management (draft, submitted, followed_up, converted)
      - SyncroRMM sync status indicator
      - Basic analytics (conversion funnel, popular services)
    </admin_dashboard>

    <pdf_generation>
      - Professional quote document
      - Company branding (logo, colors)
      - Itemized service breakdown
      - Terms and conditions
      - Validity period display
      - Contact information
    </pdf_generation>
  </core_features>

  <database_schema>
    <tables>
      <quotes>
        - id (UUID, PK)
        - company_name (VARCHAR 255, nullable)
        - contact_name (VARCHAR 255, not null)
        - contact_email (VARCHAR 255, not null)
        - contact_phone (VARCHAR 50, nullable)
        - employee_count (INT, nullable)
        - industry (VARCHAR 100, nullable)
        - current_it_situation (TEXT, nullable)
        - status (ENUM: draft, submitted, viewed, followed_up, converted, expired)
        - access_token (VARCHAR 64, unique, not null)
        - monthly_total (DECIMAL 10,2)
        - setup_total (DECIMAL 10,2)
        - syncro_lead_id (VARCHAR 100, nullable)
        - syncro_synced_at (DATETIME, nullable)
        - is_existing_customer (BOOLEAN, default false)
        - source (VARCHAR 50, default 'website')
        - utm_source, utm_medium, utm_campaign (VARCHAR 100 each)
        - ip_address (VARCHAR 45)
        - user_agent (TEXT)
        - created_at, updated_at, submitted_at, expires_at (DATETIME)
      </quotes>

      <quote_items>
        - id (UUID, PK)
        - quote_id (UUID, FK to quotes, cascade delete)
        - category (ENUM: gps_monitoring, support_plan, voip, web_hosting, email, hardware, addon)
        - product_code (VARCHAR 50, not null)
        - product_name (VARCHAR 255, not null)
        - description (TEXT, nullable)
        - quantity (INT, default 1)
        - unit_price (DECIMAL 10,2, not null)
        - setup_price (DECIMAL 10,2, default 0)
        - billing_frequency (ENUM: monthly, yearly, one_time)
        - tier (VARCHAR 50, nullable)
        - is_recommended (BOOLEAN, default false)
        - created_at (DATETIME)
      </quote_items>

      <quote_activity>
        - id (UUID, PK)
        - quote_id (UUID, FK to quotes, cascade delete)
        - action (VARCHAR 50, not null: created, step_completed, submitted, viewed, pdf_generated, synced_syncro, status_changed)
        - step_name (VARCHAR 50, nullable)
        - details (JSON, nullable)
        - ip_address (VARCHAR 45, nullable)
        - created_at (DATETIME)
      </quote_activity>

      <quote_notifications>
        - id (UUID, PK)
        - quote_id (UUID, FK to quotes, cascade delete)
        - notification_type (ENUM: email, webhook)
        - recipient (VARCHAR 255, not null)
        - subject (VARCHAR 255, nullable)
        - body (TEXT, nullable)
        - status (ENUM: pending, sent, failed)
        - attempts (INT, default 0)
        - last_attempt_at, sent_at (DATETIME, nullable)
        - error_message (TEXT, nullable)
        - created_at (DATETIME)
      </quote_notifications>
    </tables>
  </database_schema>

  <api_endpoints_summary>
    <public_quotes>
      - POST /api/quotes (create quote, returns token)
      - GET /api/quotes/{token} (get quote by token)
      - PUT /api/quotes/{token} (update quote)
      - POST /api/quotes/{token}/submit (finalize)
      - GET /api/quotes/{token}/pdf (generate PDF)
    </public_quotes>

    <admin_quotes>
      - GET /api/admin/quotes (list with filters)
      - GET /api/admin/quotes/{id} (detail view)
      - PUT /api/admin/quotes/{id} (update status/notes)
      - GET /api/admin/quotes/stats (analytics)
      - POST /api/admin/quotes/{id}/sync-syncro (manual sync)
    </admin_quotes>

    <syncro_proxy>
      - GET /api/syncro/check-customer?email={email} (duplicate check)
    </syncro_proxy>
  </api_endpoints_summary>

  <ui_layout>
    <main_structure>
      Full-width wizard container with centered content (max-width 1200px).
      Progress bar at top showing 7 steps.
      Main content area with current step.
      Fixed bottom navigation (Back/Next buttons).
      Running total display in corner/sidebar on desktop.
    </main_structure>

    <wizard_step_layout>
      Step title with icon.
      Optional subtitle/description.
      Main content area (cards, forms, selections).
      Expandable info sections.
      Step-specific help text.
    </wizard_step_layout>

    <pricing_card_layout>
      Card with tier name and price header.
      Feature list with checkmarks.
      "Most Popular" badge for recommended tier.
      Select button at bottom.
      Expandable "Learn more" section.
    </pricing_card_layout>

    <admin_layout>
      Integrated into existing GuruRMM dashboard.
      Left sidebar navigation (add "Quotes" menu item).
      Main content area with quote listing.
      Slide-out panel for quick view.
      Full page for quote details.
    </admin_layout>
  </ui_layout>

  <design_system>
    <color_palette>
      Match azcomputerguru.com website theme:
      - Primary Dark: #333d49 (dark blue-gray)
      - Accent Orange: #fe7400 (call-to-action, highlights)
      - Navy: #113559 (headers, dark elements)
      - White: #ffffff (backgrounds, text on dark)
      - Black: #000000 (text)
      - Gray: #4d4d4d (secondary text)
    </color_palette>

    <typography>
      - Font Family: Lexend (Google Fonts) - same as main website
      - Headings: Bold weight, navy or dark
      - Body: Regular weight, gray/black
      - Prices: Bold, larger size, orange accent (#fe7400)
    </typography>

    <effects>
      - Clean, professional cards with subtle shadows
      - Smooth transitions (200ms)
      - Orange hover effects on buttons
      - Progress bar with orange fill
      - Step transition slides
      - Consistent with main website aesthetic
    </effects>
  </design_system>

  <implementation_steps>
    <step number="1">
      <title>Foundation - Database and API Setup</title>
      <tasks>
        - Create database migration for quote tables
        - Build SQLAlchemy models (Quote, QuoteItem, QuoteActivity, QuoteNotification)
        - Create Pydantic schemas for request/response
        - Implement QuoteService with CRUD operations
        - Build public quote endpoints (/api/quotes/*)
        - Add token generation and validation
      </tasks>
    </step>

    <step number="2">
      <title>Frontend Project Setup</title>
      <tasks>
        - Initialize Vite + React + TypeScript project
        - Configure Tailwind CSS v4 with GuruRMM design tokens
        - Copy/adapt UI components from GuruRMM (Button, Card, Input)
        - Set up React Router for wizard navigation
        - Configure Axios + React Query for API calls
        - Create pricing data constants from MSP pricing docs
      </tasks>
    </step>

    <step number="3">
      <title>Wizard Core Implementation</title>
      <tasks>
        - Build WizardContainer with progress tracking
        - Implement WizardProgress component
        - Create each step component (Steps 1-7)
        - Build pricing card components
        - Implement quantity selectors and toggles
        - Wire up quote creation/update API calls
        - Add form validation for each step
      </tasks>
    </step>

    <step number="4">
      <title>Educational Content and Polish</title>
      <tasks>
        - Build ExpandableInfo component
        - Add feature descriptions and comparisons
        - Implement tier comparison tables
        - Add Framer Motion animations
        - Ensure mobile responsiveness
        - Add loading states and error handling
      </tasks>
    </step>

    <step number="5">
      <title>Integrations</title>
      <tasks>
        - Build SyncroService for API integration
        - Implement duplicate customer check
        - Create lead in SyncroRMM on submit
        - Build NotificationService for emails
        - Create email templates
        - Implement PDF generation
      </tasks>
    </step>

    <step number="6">
      <title>Admin Dashboard</title>
      <tasks>
        - Add admin API endpoints
        - Build quote listing page in GuruRMM
        - Create quote detail view
        - Implement filters and search
        - Add status management
        - Build basic analytics view
      </tasks>
    </step>

    <step number="7">
      <title>Deployment and Website Link</title>
      <tasks>
        - Build production frontend bundle
        - Deploy to quote.azcomputerguru.com or ClaudeTools server
        - Add noindex meta tags to quote wizard
        - Configure CORS for API access
        - Add "Get a Quote" button/link on azcomputerguru.com
        - End-to-end testing
      </tasks>
    </step>
  </implementation_steps>

  <success_criteria>
    <functionality>
      - Complete wizard flow from start to submission
      - All pricing calculations accurate
      - Quote saved to database with all items
      - SyncroRMM lead created on submission
      - Email notifications sent
      - PDF generation works
      - Admin can view and manage all quotes
    </functionality>

    <user_experience>
      - Wizard intuitive for non-technical users
      - Expandable info provides education without cluttering
      - Progress clearly visible at all times
      - Mobile-friendly on all devices
      - Fast loading and responsive interactions
    </user_experience>

    <technical_quality>
      - No mock data - all real database operations
      - Proper error handling throughout
      - API validation on both client and server
      - Secure token-based quote access
      - Rate limiting on public endpoints
    </technical_quality>

    <design_polish>
      - Matches GuruRMM design system
      - Consistent glassmorphism styling
      - Smooth animations and transitions
      - Professional appearance suitable for business
    </design_polish>
  </success_criteria>

  <pricing_data_reference>
    <source_files>
      - /projects/msp-pricing/docs/gps-pricing-structure.md
      - /projects/msp-pricing/docs/voip-pricing-structure.md
      - /projects/msp-pricing/docs/web-email-hosting-pricing.md
    </source_files>
  </pricing_data_reference>
</project_specification>
