Readmigo

AI-Powered English Learning Through Reading

Quick Links

Service	URL
Official Website	https://readmigo.app
Web App (PWA)	https://web.readmigo.app
Admin Dashboard	https://dashboard.readmigo.app
API (Production)	https://readmigo-api.fly.dev
API (Debug)	https://readmigo-debug.fly.dev
CDN / Assets	https://cdn.readmigo.com
iOS App	App Store (Coming Soon)
Android App	Google Play (Coming Soon)

Deployed Services

Production Environment

Service	Platform	URL	Description
Web App	Vercel	https://web.readmigo.app	Next.js 16 PWA client
API Server	Fly.io	https://readmigo-api.fly.dev	NestJS backend
Dashboard	Vercel	https://dashboard.readmigo.app	Admin management panel
CDN	Cloudflare R2	https://cdn.readmigo.com	Static assets & EPUB files

Debug/Staging Environment

Service	Platform	URL	Description
API Server	Fly.io	https://readmigo-debug.fly.dev	Debug backend (LOG_LEVEL=debug)

Infrastructure Services

Service	Provider	Region	Purpose
Database	PostgreSQL 15	nrt (Tokyo)	Primary data store
Cache	Redis 7	nrt (Tokyo)	Session & AI response cache
Object Storage	Cloudflare R2	Global	EPUB files, covers, audio
Monitoring	Sentry	-	Error tracking

AI Service Providers

Provider	Model	Use Case	Dashboard
DeepSeek	deepseek-chat	Primary (cost-effective)	https://platform.deepseek.com
OpenAI	gpt-4o-mini	Fallback	https://platform.openai.com
Anthropic	Claude	Premium quality	https://console.anthropic.com
Alibaba	Qwen	Chinese content	https://dashscope.console.aliyun.com

OAuth Providers

Provider	Console	Purpose
Apple	https://developer.apple.com/account	Sign in with Apple
Google	https://console.cloud.google.com/apis/credentials	Google OAuth

Deployment Commands

# Deploy backend to debug
fly deploy -c fly.debugging.toml

# Deploy backend to production
fly deploy -c fly.production.toml

# Web & Dashboard auto-deploy on push to main via Vercel

Overview

Readmigo is an AI-native English reading and learning application that helps users improve their English skills through immersive reading experiences with intelligent AI assistance.

Architecture

readmigo/
├── apps/
│   ├── backend/           # NestJS API server
│   ├── web/               # Next.js 16 PWA web client
│   ├── mobile/            # Expo React Native mobile app
│   ├── dashboard/         # React Admin management panel
│   └── website/           # Official website (readmigo.app)
├── packages/
│   ├── database/          # Prisma schema and migrations
│   └── shared/            # Shared types and utilities
├── scripts/
│   └── book-ingestion/    # Book processing pipeline
├── ios/
│   └── Readmigo/          # SwiftUI iOS client (primary)
├── android/
│   └── app/               # Kotlin Android client (primary)
└── docs/                  # Documentation

Tech Stack

Backend

• Runtime: Node.js 20 LTS
• Framework: NestJS 10.x
• Database: PostgreSQL 15 + Prisma ORM
• Cache: Redis 7
• Storage: Cloudflare R2

AI Services

• Primary: DeepSeek (cost-effective)
• Fallback: OpenAI GPT-4o-mini
• Premium: Anthropic Claude

iOS Client

• Language: Swift 5.9+
• UI Framework: SwiftUI
• Minimum iOS: 17.0
• Authentication: Sign in with Apple

Web Client

• Framework: Next.js 16 + TypeScript
• UI Library: shadcn/ui + Tailwind CSS 4
• State: Zustand + TanStack Query
• PWA: next-pwa with offline support
• Auth: NextAuth.js (Apple/Google)

Mobile App (React Native)

• Framework: Expo 54 + React Native 0.81
• Language: TypeScript
• Navigation: Expo Router + React Navigation 7
• State: Zustand + TanStack Query
• Local DB: Drizzle ORM + SQLite
• Platforms: iOS 15+ / Android 8.0+

Android Client

• Language: Kotlin
• UI Framework: Jetpack Compose
• Minimum SDK: 26 (Android 8.0)
• Architecture: MVVM + Clean Architecture

Dashboard

• Framework: React 18 + TypeScript
• Admin: React Admin
• UI Library: Ant Design 5.x

Features

Core Reading Features

• EPUB book library with 200+ public domain classics
• Customizable reader (themes, font sizes)
• Reading progress sync across devices

AI-Powered Learning

• Word Explanation: Tap any word for instant definitions
• Sentence Simplification: Simplify complex sentences
• Translation: Translate passages to native language
• Context Q&A: Ask questions about the content

Vocabulary Learning

• Save words while reading
• SM-2 spaced repetition algorithm
• Flashcard review sessions
• Progress tracking and statistics

Getting Started

Prerequisites

• Node.js 20+
• pnpm 8+
• PostgreSQL 15+
• Redis 7+
• Xcode 15+ (for iOS development)

Installation

# Clone the repository
git clone https://github.com/your-org/readmigo.git
cd readmigo

# Install dependencies
pnpm install

# Setup environment variables
cp apps/backend/.env.example apps/backend/.env

# Setup database
pnpm --filter database db:push

# Start development servers
pnpm dev

Environment Variables

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/readmigo
REDIS_URL=redis://localhost:6379

# AI Services
DEEPSEEK_API_KEY=your_key
OPENAI_API_KEY=your_key
ANTHROPIC_API_KEY=your_key

# Storage
R2_ACCOUNT_ID=your_account
R2_ACCESS_KEY_ID=your_key
R2_SECRET_ACCESS_KEY=your_secret
R2_BUCKET_NAME=readmigo

# Auth
JWT_SECRET=your_secret
JWT_REFRESH_SECRET=your_refresh_secret
APPLE_CLIENT_ID=com.readmigo.app
APPLE_TEAM_ID=your_team_id

iOS Development

# Open Xcode project
cd ios/Readmigo
open Readmigo.xcodeproj

# Or use xcodebuild
xcodebuild -scheme Readmigo -destination 'platform=iOS Simulator,name=iPhone 15'

API Endpoints

Authentication

• POST /api/v1/auth/apple - Sign in with Apple
• POST /api/v1/auth/google - Sign in with Google
• POST /api/v1/auth/refresh - Refresh access token

Books

• GET /api/v1/books - List all books
• GET /api/v1/books/:id - Get book details
• GET /api/v1/books/:id/content/:chapterId - Get chapter content

Reading

• GET /api/v1/reading/library - Get user's library
• POST /api/v1/reading/library/:bookId - Add to library
• PATCH /api/v1/reading/progress/:bookId - Update progress

AI

• POST /api/v1/ai/explain - Explain word
• POST /api/v1/ai/simplify - Simplify sentence
• POST /api/v1/ai/translate - Translate paragraph
• POST /api/v1/ai/qa - Ask question about content

Vocabulary

• GET /api/v1/vocabulary - Get user's vocabulary
• POST /api/v1/vocabulary - Add word
• GET /api/v1/vocabulary/review - Get words due for review
• POST /api/v1/vocabulary/:id/review - Submit review result

Book Ingestion

The book ingestion pipeline processes EPUB files from public domain sources:

# Ingest from Standard Ebooks
pnpm --filter book-ingestion ingest:standard-ebooks

# Ingest from Project Gutenberg
pnpm --filter book-ingestion ingest:gutenberg

Project Structure

Backend Modules

• auth - JWT authentication with Apple/Google Sign In
• users - User management and profiles
• books - Book and chapter management
• reading - Reading progress and sessions
• ai - Multi-provider AI service with smart routing
• vocabulary - Word storage and spaced repetition
• subscription - In-app purchase verification

iOS Features

• Auth - Sign in with Apple integration
• Library - Personal bookshelf management
• Reader - WKWebView-based EPUB renderer
• AI - Text selection and AI interaction panel
• Learning - Vocabulary and review system
• Profile - User settings and preferences

Documentation

Comprehensive project documentation is organized by module in the /docs directory:

• account/ - User account and permissions system
• agora/ - Community features (comments, discussions)
• ai/ - AI integration and caching strategies
• algorithm/ - Learning algorithms (spaced repetition, etc.)
• android/ - Android client documentation
• api/ - API specifications and technical architecture
• architecture/ - System architecture and design decisions
• audiobook/ - Audiobook features and integration
• author/ - Author profiles and book relationships
• content/ - Content management and discovery
• dashboard/ - Admin panel documentation
• design/ - Design system and typography
• features/ - Feature specifications and requirements
• infrastructure/ - Deployment, logging, and infrastructure
• ios/ - iOS client specifications and features
• learning/ - Learning system and vocabulary features
• legal/ - Privacy policy and terms of service
• product/ - Product requirements and roadmap
• react-native/ - React Native mobile app documentation
• reader/ - Reading experience and EPUB rendering
• sources/ - Book sources (Gutenberg, Standard Ebooks, etc.)
• version-control/ - Version management strategy
• web/ - Web client documentation

For detailed documentation, see docs/README.md

License

MIT License - see LICENSE for details