KeyCraft – Technical write-up
Table of Contents
1. System Design
High-level architecture overview of the KeyCraft platform.
2. Frontend
The frontend consists of two main applications: a marketing site built with Next.js and a piano editor built with Create React App.
Marketing Site
- Next.js App Router with TypeScript and CSS Modules
- Authentication flows with NextAuth/Auth.js
- Stripe integration for subscription management
Piano Editor
- Create React App with React 18
- Web Audio API via Tone.js for playback
Performance Optimizations
- React refs and memoization for performance
- CloudFront CDN for static asset delivery
3. Backend
The backend is built on Next.js API routes with DynamoDB for persistence and Stripe for billing.
API Architecture
- Next.js Route Handlers (Node runtime)
- JSON responses with cookie-based sessions
- Session bridge endpoint for server-truth sync
- Cross-domain logout hygiene
Authentication & Billing
- NextAuth/Auth.js with custom DynamoDB adapter
- Stripe Payment Links with webhook integration
- Subscription lifecycle management
- Per-user quota enforcement
Data Model
- Single-table DynamoDB design (user-centric)
- User: id, email, hasPaid, activePlans, subscription fields
- MIDI downloads: count, resetDate, totalDownloads
- Monthly quota resets and tracking
4. MLOps
AI transcription service deployed on Google Cloud Run with PyTorch-based models.
Transcription Pipeline
- Python Flask service with PyTorch models
- Optional ffmpeg audio preprocessing
- CPU-only inference with thread caps
- Bounded logs and aggressive cleanup
API Endpoints
- GET /health and /ready for monitoring
- POST /transcribe (multipart form audio)
- X-Transcription-Secret header authentication
- 100MB upload limit with 1800s timeout
Deployment
- Docker containerized Flask app
- Cloud Run: min=0, max=5, concurrency=1
- 1 vCPU, 2GiB memory allocation
- Cold start optimization
5. AWS Infrastructure
Cloud infrastructure built on AWS services for scalability and reliability.
Storage & CDN
- DynamoDB for user data and session management
- S3 for static MIDI assets and media files
- CloudFront CDN for global asset delivery
- CORS configuration for cross-origin requests
Security & Access
- Origin Access Control (OAC) for S3
- Bucket policies restricting CloudFront access
- Cookie scoping to .keycraft.org domain
Monitoring & Ops
- CloudFront analytics and caching metrics
- DynamoDB performance monitoring
- Vercel analytics
Links
Website: keycraft.org
App: app.keycraft.org
Marketing Repo: github.com/Condor3333/keycraftpage2.git
Editor Repo: github.com/Condor3333/keycraftapp.git