Skip to content

technical_implementation.md

Latest commit

 

History

History
106 lines (89 loc) · 3.84 KB

technical_implementation.md

File metadata and controls

106 lines (89 loc) · 3.84 KB

Technical Implementation

1. Framework & Libraries

  • Framework: Next.js 14 (App Router) with React 18
  • Package Manager: Bun
  • Styling: TailwindCSS + shadcn/ui
  • Animations: Framer Motion
  • Icons: Lucide-react
  • State/Data: Convex client SDK (real-time), optional React Query
  • Auth: Better-Auth SDK
  • AI: OpenAI Node SDK
  • Docs Enrichment: Firecrawl SDK, Vector DB (Convex / Pinecone)
  • Email: Resend SDK + @convex-dev/resend component
  • (Future) Voice: Vapi SDK
  • (Future) Payments: Autumn SDK
  • Analytics: Recharts
  • Developer Experience: TypeScript, ESLint, Prettier
  • Hosting: Vercel

2. Core MVP (Convex + Resend)

  • Convex
    • Collections: tickets, users, teams.
    • Real-time subscriptions: tickets stream → agent dashboard and customer ticket views.
    • Dashboard: Next.js frontend with live ticket list + assignment view.
  • Resend Integration
    • @convex-dev/resend component: Official Convex-Resend integration with:
      • Queuing: Send unlimited emails with guaranteed delivery
      • Batching: Automatic batching for efficient API usage
      • Durable execution: Retry logic with Convex workpools
      • Idempotency: Prevents duplicate emails with managed keys
      • Rate limiting: Respects Resend API limits
    • Email triggers:
      • Ticket creation → "Ticket received" confirmation
      • Status updates → "Ticket resolved/updated" notifications
    • Webhook integration: Real-time email delivery status tracking

3. AI Enhancements (OpenAI + Firecrawl)

  • OpenAI
    • On ticket creation:
      • Categorize: {priority, type}.
      • Draft suggested reply.
      • Generate conversation summary.
    • Conversation model:
      • AI-generated replies, when accepted/sent, are stored as messages in the ticket conversation.
      • Both agents and customers see AI messages inline in the conversation thread.
      • Agents can send manual replies independent of AI suggestions at any time.
  • Firecrawl Knowledge Base
    • Pre-scraped Documentation Sources:
      • Convex docs (docs.convex.dev) → Real-time database, functions, auth
      • Resend docs (resend.com/docs) → Email delivery, templates, webhooks
      • Firecrawl docs (docs.firecrawl.dev) → Web scraping, data extraction
    • Implementation:
      • Store scraped content in Convex knowledgeBase collection
      • Full-text search across documentation content
      • On ticket creation: query knowledge base → retrieve relevant doc snippets
      • AI reply enriched with official documentation context
    • Demo Value: Shows real-world knowledge base integration using actual tool docs

4. Auth & Roles (Better-Auth)

  • Role-based access:
    • Customer: create tickets, view ticket history.
    • Agent: view team dashboard, assign/reply to tickets (manual replies + optional AI-assisted drafts).
  • Support for organizations/teams:
    • Agents belong to support teams.
    • Tickets assigned by team.

5. (Future) Monetization (Autumn)

  • Planned: upgrade flow and plan state in Convex user profile.

6. (Future) Voice Ticketing (Vapi)

  • Planned: microphone capture → transcription → ticket creation → email trigger.

7. Stretch Goals

  • Analytics dashboard for agents:
    • Ticket volume, categories, response time.
  • Multi-language support (OpenAI translation).
  • SLA reminders (email or dashboard alerts).

8. Development Order

  1. Next.js + Convex backend + dashboard.
  2. Resend email triggers.
  3. OpenAI categorization + draft replies.
  4. Firecrawl knowledge base setup:
    • Scrape Convex, Resend, and Firecrawl official documentation
    • Build search and management UI
    • Integrate with AI suggestions for contextual responses
  5. Better-Auth roles & login flows.
  6. Autumn Pro plan integration.
  7. Vapi voice ticketing unlock.
  8. (Stretch) Analytics dashboard.