braket.uk
AI-powered mathematics and physics tutoring platform with real-time streaming conversations, LaTeX rendering, image analysis for homework problems, and voice interaction. Named after bra-ket notation from quantum mechanics.
Overview
braket.uk is a production-grade AI tutoring platform specializing in mathematics and physics. The platform features real-time streaming responses with live LaTeX rendering, allowing students to see mathematical equations formatted beautifully as the AI explains concepts.
Users can upload images of homework problems for AI analysis, use voice input for hands-free interaction, and compose complex equations using an integrated mathematical editor. The architecture prioritizes low-latency streaming and connection resilience for a seamless learning experience.
Tech Stack
Frontend
- Vue 3 (Composition API)
- Quasar 2 (Material Design)
- Pinia state management
- KaTeX + MathLive
Backend
- FastAPI (async Python)
- SQLAlchemy + Alembic
- PostgreSQL 16
- Gunicorn + Uvicorn
Real-Time
- Socket.IO (bidirectional)
- Chunk-based streaming
- Auto-reconnection
- WebSocket + polling fallback
Infrastructure
- Docker Compose
- GitHub Actions CI/CD
- Nginx reverse proxy
- DigitalOcean
Streaming Architecture
Real-time AI responses stream character-by-character while maintaining proper LaTeX rendering:
Client Server | | |-------- send_message ------------->| | | |<------- message_ack ---------------| (delivery confirmed) | | |<------- stream_start --------------| (streaming begins) | | |<------- message_chunk -------------| \ |<------- message_chunk -------------| } batched, throttled |<------- message_chunk -------------| / | | |<------- stream_complete -----------| (final + DB persist)
Key Features
Live LaTeX Rendering
Mathematical notation renders in real-time during streaming. Buffering strategy detects incomplete LaTeX delimiters and holds content until expressions complete, preventing rendering failures mid-stream.
Homework Image Analysis
Upload photos of handwritten problems or textbook exercises. Images are base64 encoded within Socket.IO messages, decoded server-side, and integrated into the AI conversation context for analysis.
Mathematical Equation Editor
MathLive integration provides an interactive equation editor with symbol palette. Students can compose complex expressions (integrals, matrices, Greek letters) without knowing LaTeX syntax.
Guest-to-Registered Upgrade
Frictionless onboarding - start chatting immediately as a guest. When ready to register, the guest account upgrades in place, preserving all conversation history under the new authenticated account.
Multi-Provider OAuth
Sign in with Google, Apple, or email/password. Hierarchical lookup prevents duplicate accounts - existing users can link new auth methods without losing data.
Technical Challenges
LaTeX Streaming Without Breakage
Incomplete LaTeX delimiters ($, $$) mid-stream cause KaTeX rendering failures. Implemented a buffering strategy that detects unclosed delimiters and holds content until the expression completes, rendering stable portions immediately.
Socket.IO Auth State Management
Token changes (login/logout/refresh) caused state inconsistencies. Built smart token tracking - connections reuse if token unchanged, auto-disconnect on token change, then establish new authenticated connection.
OAuth Account Linking
Users might sign up with email then try Google OAuth with same email. Hierarchical lookup: check email, then provider ID, link if match found. Prevents duplicates while supporting multiple auth methods per user.
Zero-Downtime Deployments
Database migrations during deploys risked data inconsistencies. Orchestrated deployment: Docker rebuild while old containers run, Alembic migrations with forward-compatible schema changes, health check verification before traffic switch.