Technical Architecture

TeachWise.ai Platform

Complete Technical Setup & Infrastructure Guide

⚙️

System Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                      CLIENT LAYER                            │
├─────────────────┬─────────────────┬────────────────────────┤
│  Web App        │  Mobile App     │  Mobile App            │
│  (React/Next.js)│  (iOS - Swift)  │  (Android - Kotlin)    │
└────────┬────────┴────────┬────────┴──────────┬─────────────┘
         │                 │                    │
         └─────────────────┼────────────────────┘
                           │
┌──────────────────────────▼─────────────────────────────────┐
│                   API GATEWAY LAYER                         │
│   (AWS API Gateway / Kong / Express Gateway)                │
│   - Rate Limiting  - Authentication  - Request Routing      │
└──────────────────────────┬─────────────────────────────────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                  │
┌────────▼────────┐ ┌─────▼──────┐  ┌───────▼────────┐
│  Auth Service   │ │ AI Service  │  │  Core API      │
│  (Next-Auth/    │ │ (OpenAI/    │  │  (Node.js/     │
│   Firebase)     │ │  Anthropic) │  │   Python)      │
└────────┬────────┘ └─────┬──────┘  └───────┬────────┘
         │                │                  │
         └────────────────┼──────────────────┘
                          │
┌─────────────────────────▼──────────────────────────────────┐
│                     DATA LAYER                              │
├──────────────┬────────────────┬────────────────────────────┤
│  PostgreSQL  │  MongoDB       │  Redis Cache               │
│  (User data, │  (Curriculum,  │  (Sessions,                │
│   schedules) │   resources)   │   API responses)           │
└──────────────┴────────────────┴────────────────────────────┘
                          │
┌─────────────────────────▼──────────────────────────────────┐
│                  EXTERNAL SERVICES                          │
├──────────────┬────────────────┬────────────────────────────┤
│  Cloud School│  Gmail API     │  Payment Gateway           │
│  Integration │  (OAuth 2.0)   │  (Stripe/M-Pesa)           │
└──────────────┴────────────────┴────────────────────────────┘

Architecture Philosophy:

Microservices-based architecture for scalability, with clear separation of concerns and API-first design. Start with managed services (Firebase, AWS) to reduce operational overhead, then migrate to custom infrastructure as needed.

1 AI/ML Technology Stack

PHASE 1: MVP (Months 0-6)

Recommended: Anthropic Claude API

Why Anthropic Claude?

  • ✓ Superior educational content generation
  • ✓ Better context understanding (200K tokens)
  • ✓ More accurate curriculum alignment
  • ✓ Strong safety and ethical guardrails
  • ✓ Excellent at structured outputs (JSON)

Model Recommendation

Primary: Claude Sonnet 4.5

Lesson plans, curriculum queries, complex reasoning

Cost: ~$3 per 1M input tokens, $15 per 1M output tokens

Secondary: Claude Haiku 4

Quick responses, simple queries, chatbot

Cost: ~$0.25 per 1M input tokens, $1.25 per 1M output tokens

Alternative: OpenAI GPT-4

Pros:

  • • More established ecosystem
  • • Wider community support
  • • Good multimodal capabilities

Cons:

  • • Higher cost (~$30/1M output tokens)
  • • Shorter context window (128K)
  • • Less consistent for educational content

💡 Cost Optimization Strategy:

  • • Use Haiku for 70% of interactions (simple queries, chat)
  • • Reserve Sonnet for complex lesson planning (30% of requests)
  • • Implement aggressive caching for common curriculum queries
  • • Expected cost: $0.50-1.50 per user per month
PHASE 2: OPTIMIZATION (Months 6-18)

Hybrid Approach: API + Fine-tuned Models

Option A: Fine-tune Smaller Models

Fine-tune models specifically for Kenyan/Ugandan curricula on your own infrastructure.

Recommended Models:

  • • Llama 3.1 8B/70B (open source, Meta)
  • • Mistral 7B (efficient, good quality)
  • • DeepSeek Coder (if generating code-based content)

Benefits:

  • • Reduce API costs by 60-80%
  • • Better curriculum alignment
  • • Data privacy control
  • • Faster response times

Option B: Retrieval-Augmented Generation (RAG)

Combine existing APIs with vector database for curriculum-specific knowledge.

Stack:

  • • Vector DB: Pinecone or Weaviate (managed) OR Qdrant (self-hosted)
  • • Embeddings: OpenAI text-embedding-3-large or Sentence Transformers
  • • Storage: Store full Kenya CBC, Uganda curricula, past lesson plans
  • • Cost: $50-200/month for vector DB + reduced LLM tokens
PHASE 3: SCALE (Month 18+)

Own Infrastructure with Custom Models

Infrastructure Setup

  • GPU Servers: AWS/GCP with NVIDIA A100 or H100
  • Model Serving: vLLM, TGI, or Ray Serve
  • Base Models: Llama 3.1 70B or Mixtral 8x7B
  • Fine-tuning: LoRA/QLoRA on curriculum data
  • Monitoring: Weights & Biases, Arize AI

Economics at Scale

API Costs (50K users):

$25,000-75,000/month

Self-hosted (50K users):

$8,000-15,000/month

Savings:

$10,000-60,000/month

🎯 Recommendation:

Start with Anthropic API, implement RAG at 1,000 users, and consider self-hosting at 20,000+ users when economics justify infrastructure investment.

2 Complete Technology Stack

Frontend Stack

Web Application

  • • Framework: Next.js 14+ (React)
  • • UI Library: Tailwind CSS + shadcn/ui
  • • State Management: Zustand or React Context
  • • Forms: React Hook Form + Zod

Mobile Apps

  • • iOS: Swift + SwiftUI
  • • Android: Kotlin + Jetpack Compose
  • • Alternative: React Native (faster MVP)

Backend Stack

API Server

  • • Primary: Node.js (Express/Fastify)
  • • Alternative: Python (FastAPI) for ML ops
  • • API: RESTful + GraphQL (Apollo Server)

Authentication

  • • Auth: NextAuth.js or Firebase Auth
  • • OAuth: Google, Cloud School integration
  • • Session: JWT with Redis

Database & Storage

Relational Data

• PostgreSQL 15+ (users, schedules, subscriptions)

• ORM: Prisma or Drizzle ORM

Document Storage

• MongoDB (curriculum, resources, lesson plans)

• ODM: Mongoose

Caching

• Redis (sessions, API responses, rate limiting)

File Storage

• AWS S3 / CloudFlare R2 (PDFs, images, resources)

Infrastructure & DevOps

Hosting (MVP)

• Vercel (Next.js frontend)

• Railway/Render (API server)

• Supabase/Neon (managed PostgreSQL)

Hosting (Scale)

• AWS/GCP (ECS, Cloud Run, or Kubernetes)

• CloudFlare (CDN, DDoS protection)

Monitoring

• Sentry (error tracking)

• DataDog/NewRelic (APM)

• PostHog (product analytics)

3 Cloud School Integration

Integration Architecture

Connect to Cloud School's API to fetch student data, grades, and attendance by grade level.

Integration Flow:

  1. Teacher authenticates with Cloud School OAuth
  2. Store OAuth tokens securely (encrypted in PostgreSQL)
  3. Fetch teacher's class data and student roster
  4. Sync grade-level data daily (batch job)
  5. Display student performance metrics in dashboard

API Endpoints Needed:

  • • /api/auth/cloudschool
  • • /api/classes
  • • /api/students
  • • /api/grades
  • • /api/attendance

Data to Sync:

  • • Student names & IDs (by grade)
  • • Current grades & performance
  • • Attendance records
  • • Assignment submissions
  • • Class schedules

Data Privacy & Security

  • 🔒 Encryption: All student data encrypted at rest (AES-256) and in transit (TLS 1.3)
  • 🔒 Access Control: Teachers only see their own classes, no cross-class data access
  • 🔒 Compliance: GDPR-compliant, data minimization, right to deletion
  • 🔒 Audit Logs: Track all data access and modifications

4 Development Workflow & Tools

Version Control & CI/CD

  • Git Repository

    GitHub (private repo) with branch protection

  • CI/CD Pipeline

    GitHub Actions for automated testing & deployment

  • Environments

    Development → Staging → Production

Testing Strategy

  • Unit Tests

    Jest, Vitest (80% coverage target)

  • Integration Tests

    Playwright, Cypress for E2E

  • AI Testing

    LangSmith for LLM response evaluation

Code Quality

  • • Linting: ESLint, Prettier
  • • Type Safety: TypeScript strict mode
  • • Code Review: Required PR approvals
  • • Security: Snyk for dependency scanning

Documentation

  • • API Docs: Swagger/OpenAPI
  • • Internal Docs: Notion or GitBook
  • • Code Comments: JSDoc/TSDoc
  • • Architecture: C4 diagrams

5 Security & Compliance

Authentication

  • • OAuth 2.0 (Gmail, Cloud School)
  • • JWT with short expiry (15min)
  • • Refresh token rotation
  • • 2FA option for premium users

Data Protection

  • • AES-256 encryption at rest
  • • TLS 1.3 for data in transit
  • • Regular security audits
  • • Data backup (daily + weekly)

Compliance

  • • GDPR compliance
  • • Kenya Data Protection Act
  • • Regular privacy impact assessments
  • • Cookie consent management

Security Best Practices

  • ✓ Rate limiting on all API endpoints
  • ✓ Input validation and sanitization
  • ✓ SQL injection prevention (parameterized queries)
  • ✓ XSS protection (CSP headers)
  • ✓ CSRF tokens for state-changing operations
  • ✓ Regular dependency updates
  • ✓ Penetration testing (quarterly)
  • ✓ Incident response plan

6 Infrastructure Cost Estimates

MVP Phase (0-1,000 users)

Service Monthly Cost
Vercel (hosting) $20
Railway/Render (API) $20-50
Supabase (database) $25
Anthropic API (AI) $200-500
Redis (Upstash) $0-10
CloudFlare R2 (storage) $5-15
Monitoring (Sentry, PostHog) $50
Total Monthly $320-670

Growth Phase (10,000 users)

Service Monthly Cost
AWS/GCP (compute + database) $500-1,000
Anthropic API + RAG $3,000-5,000
Storage (S3/R2) $100-200
Vector DB (Pinecone) $150-300
CDN (CloudFlare) $200
Monitoring & Analytics $300-500
Total Monthly $4,250-7,200

Scale Phase (50,000+ users)

Service Monthly Cost
AWS/GCP (infrastructure) $3,000-5,000
Self-hosted AI (GPUs) $8,000-12,000
Storage & CDN $500-1,000
Database (managed) $1,000-2,000
Monitoring & Security $1,000-1,500
Total Monthly $13,500-21,500

© 2025 TeachWise.ai Technical Documentation

Version 1.0 - Last Updated: November 2025