Skip to content

architecture.md

Latest commit

 

History

History
407 lines (322 loc) · 10.1 KB

architecture.md

File metadata and controls

407 lines (322 loc) · 10.1 KB

TutorialChat Architecture

Product: Standalone web application for AI-powered MakeCode tutorial authoring
Status: Design phase
Created: 2026-04-12

Design Principles

  1. Standalone - No OpenClaw dependency
  2. Self-contained - Own LLM backend (Claude/OpenAI API)
  3. Simple deployment - Single web app, easy to host
  4. Teacher-friendly - No technical setup required
  5. Free tier - Basic usage free, premium for advanced features

Architecture

High-Level Stack

┌─────────────────────────────────────────┐
│         TutorialChat Web App            │
├─────────────────────────────────────────┤
│  Frontend (React/Next.js)               │
│  - Chat interface                       │
│  - Live preview                         │
│  - Tutorial editor                      │
├─────────────────────────────────────────┤
│  Backend (FeathersJS API)               │
│  - LLM integration (Claude/OpenAI)      │
│  - Tutorial CRUD                        │
│  - GitHub publishing                    │
│  - User accounts                        │
├─────────────────────────────────────────┤
│  Database (PostgreSQL)                  │
│  - Users                                │
│  - Tutorials (drafts)                   │
│  - Generation history                   │
└─────────────────────────────────────────┘

Technology Choices

Frontend:

  • Framework: Next.js 14+ (React, TypeScript)
  • UI Library: Tailwind CSS + Headless UI (or shadcn/ui)
  • Chat UI: Custom chat component (similar to MicroChat)
  • Preview: Markdown renderer + syntax highlighting
  • Deployment: Vercel or DigitalOcean App Platform

Backend:

  • API Framework: FeathersJS (same as MicroChat for consistency)
  • Language: Node.js + TypeScript
  • LLM Provider: Anthropic Claude API (primary) + OpenAI fallback
  • Auth: JWT + email/password (or OAuth via Auth0/Clerk)
  • GitHub Integration: Octokit (GitHub API client)
  • Deployment: DigitalOcean App Platform or Railway

Database:

  • DB: PostgreSQL (managed instance)
  • ORM: Sequelize or Prisma
  • Migrations: Knex or Prisma Migrate

External Services:

  • LLM: Anthropic Claude API (pay-per-token)
  • Storage: S3-compatible (DO Spaces or Cloudflare R2) for images
  • GitHub: GitHub API (for publishing tutorials)
  • Email: SendGrid or Resend (for notifications)

Data Model

Users

interface User {
  id: string
  email: string
  name: string
  githubUsername?: string
  githubToken?: string  // Encrypted, for publishing
  subscription: 'free' | 'pro'
  createdAt: Date
  updatedAt: Date
}

Tutorials

interface Tutorial {
  id: string
  userId: string
  title: string
  slug: string
  markdown: string  // The tutorial content
  status: 'draft' | 'published'
  publishedUrl?: string  // GitHub tutorial URL
  githubRepo?: string
  metadata: {
    targetAge?: string
    complexity?: 'beginner' | 'intermediate' | 'advanced'
    estimatedMinutes?: number
    topics?: string[]
  }
  createdAt: Date
  updatedAt: Date
  publishedAt?: Date
}

GenerationHistory

interface GenerationHistory {
  id: string
  userId: string
  tutorialId?: string
  prompt: string
  response: string
  tokensUsed: number
  model: string
  createdAt: Date
}

LLM Integration

Provider Setup

Anthropic Claude (Primary):

  • API Key stored in environment variables
  • Model: claude-3-5-sonnet-20241022 (or latest)
  • System prompt: Tutorial authoring expert
  • Streaming: Yes (for real-time generation)

OpenAI (Fallback):

  • API Key stored in environment variables
  • Model: gpt-4o or gpt-4-turbo
  • Use if Claude unavailable or rate-limited

System Prompt

See: prompts/tutorial-generator.md (to be created)

Key elements:

  • MakeCode tutorial format specification
  • Block syntax reference
  • Pedagogical best practices
  • Age-appropriate language guidelines
  • Step-by-step structure

API Wrapper

Service: services/llm/tutorial-generator.ts

class TutorialGenerator {
  async generate(prompt: string, context?: TutorialContext): Promise<string>
  async refine(markdown: string, instruction: string): Promise<string>
  async addStep(markdown: string, stepDescription: string): Promise<string>
  async simplify(markdown: string, targetAge: string): Promise<string>
}

Rate Limiting:

  • Free tier: 10 generations/day
  • Pro tier: Unlimited (or high limit)
  • Token budget tracking per user

User Flow

1. Landing Page

  • What is TutorialChat?
  • Example tutorials
  • Sign up / Log in

2. New Tutorial

  • Chat interface: "What tutorial do you want to create?"
  • User describes: "A tutorial teaching 6th graders about temperature sensors"
  • AI generates complete markdown
  • Preview panel shows rendered tutorial

3. Refinement

  • User: "Make step 3 simpler"
  • User: "Add an image placeholder in step 2"
  • User: "Add a challenge at the end"
  • AI updates the tutorial

4. Publishing

  • Option A: Download markdown (manual GitHub upload)
  • Option B: Connect GitHub account → one-click publish
  • Option C: Export as PDF/print

5. Management

  • Tutorial library (all drafts + published)
  • Edit existing tutorials
  • Duplicate/fork tutorials
  • Archive/delete

MVP Feature Set

Phase 1: Core Generation (Must-Have)

✅ Chat Interface

  • Message input
  • Streaming responses
  • Conversation history

✅ Tutorial Generation

  • Natural language prompt → markdown
  • Proper MakeCode format
  • Complete working code examples

✅ Preview Panel

  • Live markdown rendering
  • Syntax highlighting
  • Collapsible sections

✅ User Accounts

  • Email/password signup
  • JWT authentication
  • Basic profile

✅ Tutorial CRUD

  • Create new
  • Save drafts
  • Edit/update
  • Delete

✅ Export

  • Download markdown file
  • Copy URL (after GitHub publishing)

Phase 2: GitHub Integration (Important)

⏭ GitHub Connection

  • OAuth flow
  • Repo selection/creation
  • Token storage (encrypted)

⏭ One-Click Publish

  • Commit markdown to repo
  • Generate MakeCode URL
  • Generate QR code
  • Update tutorial status

⏭ Tutorial URLs

  • Shareable link
  • QR code download
  • Embed code

Phase 3: Advanced Features (Nice-to-Have)

⏭ AI Image Generation

  • Generate diagrams for steps
  • Upload custom images
  • Image library

⏭ Template Library

  • Pre-made tutorial templates
  • Community templates
  • Clone/customize

⏭ Collaboration

  • Share drafts with other teachers
  • Comments/feedback
  • Version history

⏭ Analytics

  • Tutorial views (if self-hosted)
  • Student completion tracking
  • Popular tutorials

Deployment Strategy

Development

  • Frontend: Localhost:3000 (Next.js dev server)
  • Backend: Localhost:3030 (FeathersJS)
  • Database: Local PostgreSQL or Docker

Staging

  • Platform: DigitalOcean App Platform (or Vercel + Railway)
  • Domain: staging.tutorialchat.app (or similar)
  • Database: Managed PostgreSQL
  • Env: Separate API keys (test mode)

Production

  • Platform: DigitalOcean App Platform
  • Domain: tutorialchat.app (or tutorialchat.forwardedu.com)
  • Database: Managed PostgreSQL (production tier)
  • CDN: Cloudflare (if needed)
  • Monitoring: Sentry + Uptime monitoring

Cost Estimate (Monthly)

Infrastructure

  • App Platform: $12-25/month (basic tier)
  • Database: $15/month (managed PostgreSQL)
  • Storage: $5/month (images)
  • Domain: $1/month

API Costs (Variable)

  • Claude API: ~$0.01-0.03 per tutorial (depending on complexity)
  • Estimate: 1000 tutorials/month = $10-30
  • Free tier: Cap at $50/month, upgrade prompt for heavy users

Total

  • Fixed: ~$35/month
  • Variable: $10-50/month (depending on usage)
  • Total: ~$50-100/month for MVP

Monetization Strategy (Optional)

Free Tier

  • 10 tutorials/month
  • Download markdown
  • Basic features

Pro Tier ($10-20/month)

  • Unlimited tutorials
  • GitHub auto-publish
  • Priority support
  • AI image generation
  • Analytics

School/District License ($500-1000/year)

  • Unlimited teachers
  • White-label option
  • Custom domain
  • SSO integration

Security & Privacy

Data Protection

  • Tutorials: User owns their content
  • Markdown storage: Encrypted at rest
  • GitHub tokens: Encrypted in database
  • LLM prompts: Not logged (privacy)

Compliance

  • COPPA: No student data (teacher tool only)
  • FERPA: N/A (no student PII)
  • GDPR: Data export + deletion support
  • SOC 2: Future (if enterprise sales)

Open Questions

  1. Branding: TutorialChat vs MakeCode Tutorial Builder vs other name?
  2. Domain: tutorialchat.app vs tutorialchat.forwardedu.com vs subdomain?
  3. GitHub requirement: Require GitHub account for all users, or optional?
  4. Free tier limits: 10 tutorials/month enough? Lower/higher?
  5. LLM provider: Claude only, or OpenAI as primary option?
  6. Hosting: DigitalOcean App Platform vs Vercel + separate API?

Next Steps

Immediate (Week 1)

  1. ✅ Finalize architecture (this doc)
  2. Create Next.js + FeathersJS boilerplate
  3. Set up Claude API integration
  4. Build basic chat UI
  5. Test tutorial generation

Short-term (Week 2-3)

  1. User authentication
  2. Database setup + models
  3. Tutorial CRUD
  4. Preview panel
  5. Download/export

Medium-term (Month 1-2)

  1. GitHub OAuth integration
  2. One-click publishing
  3. QR code generation
  4. Tutorial library UI
  5. Deployment to staging

Long-term (Month 3+)

  1. Pro tier features
  2. AI image generation
  3. Template library
  4. Analytics
  5. Public launch

Status: Architecture defined 2026-04-12. Ready to start implementation.