Ella — Voice-First English Learning App

Ella is a voice-first English learning app for Indian students built by NavGurukul. Students speak to an AI tutor named Zoe — no typing required. The app uses on-device speech recognition, AI-powered conversation, and text-to-speech to create a natural, low-pressure speaking practice experience. Platform: Android-first Flutter · Org: NavGurukul

What Ella Does

Placement test — Zoe has a short conversation to assess the student’s English level (A1–C1)
Topic-based conversations — Students pick a topic (Cricket, Bollywood, School Life, Food, Gaming, Dreams) and have a real conversation with Zoe
Free chat — Open-ended conversation on anything
Real-time feedback — Grammar corrections and vocabulary suggestions woven naturally into the conversation
Session summary — After each session, students see what they did well, new words used, and what to practice next
Progress tracking — Streak, level, and session history

Who It’s For

Indian school students (primarily Hindi-speaking) at A1–B1 English level who need speaking practice but don’t have access to English-speaking environments. The app is designed to feel like chatting with a friendly buddy, not a formal test.

Tech Stack

Frontend: Flutter (Android-first) · On-device Whisper STT · Piper TTS · DeepSeek LLM
Backend: FastAPI · PostgreSQL · Docker · AWS EC2

Design Prototype

All pages live at ella.navgurukul.org:

What	URL	Description
📚 Pedagogy	Google Doc	Teaching approach and learning design
📄 Project Summary	docs/project-summary.md	Project overview and goals
🎨 Design System	docs/zoe-design-system.md	Zoe design system reference
🎨 Design v0 (Stitch)	stitch.withgoogle.com	UI design reference for ella-v0
🎨 Design v1	ella.navgurukul.org/design/	Figma-style user flow and design system
🌐 Product v1 (Live App)	ella.navgurukul.org/v1/	Flutter web build (latest)
📊 Pilot Dashboard	ella.navgurukul.org/admin/	Live screening results
📲 Android APK	ella.navgurukul.org	Download latest release APK
⚙️ API Reference (Swagger)	ella.navgurukul.org/api/docs	Interactive API documentation
🗣️ Conversation Flow (v2)	ella.navgurukul.org/v2/conversation-flow/	Interactive conversation product experience

Notion Docs

What	URL
💬 ELLA Conversation Design	Notion
🔧 Build Log & Technical Deep Dive (Mar 24)	Notion
📝 What We Built Today — Session 2 (Mar 26)	Notion

For Claude / New Contributors — Read This First

Before reading any code, start here:

Document	When to read it
`docs/project-summary.md`	Architecture, screen flow, key files, key patterns — read once to orient yourself
`docs/zoe-design-system.md`	Colour tokens, typography, shadows, component specs — check when touching UI

Rule of thumb: Only open code files when you actually need to change something. The project summary gives you enough context to navigate without reading every screen upfront.

Project Structure

ella_flutter/
├── frontend/              # Flutter app (Android-first)
│   ├── lib/
│   │   ├── screens/       # One file per screen
│   │   ├── widgets/       # Shared UI components
│   │   ├── services/      # TTS, STT, LLM, API abstractions
│   │   ├── providers/     # ChatProvider (conversation state)
│   │   ├── models/        # ChatMessage, PlacementResult, etc.
│   │   └── theme/         # EllaColors + EllaTheme
│   ├── assets/
│   │   ├── mascot-animations/   # Zoe .webp animations
│   │   ├── chillax/             # Chillax font files
│   │   ├── piper_voices/        # Piper TTS voice models
│   │   ├── whisper/             # Whisper STT model
│   │   └── prompts/             # LLM prompt markdown files
│   └── android/                 # Android-specific config
├── backend/               # FastAPI backend
│   ├── app/
│   │   ├── core/          # Config, DB, auth, deps
│   │   ├── models/        # SQLAlchemy ORM models
│   │   ├── schemas/       # Pydantic request/response schemas
│   │   ├── routers/       # Route handlers (18 endpoints)
│   │   └── services/      # LLM service
│   ├── migrations/        # Alembic migrations
│   ├── Dockerfile
│   └── docker-compose.yml
└── docs/                  # Architecture and design docs

Running the Frontend

cd frontend
flutter pub get
flutter run

Requires a .env file inside frontend/ with LLM API keys. Copy from .env.example:

cp frontend/.env.example frontend/.env
# Fill in DEEPSEEK_API_KEY

Running the Backend

With Docker (recommended)

cd backend
cp .env.example .env
# Fill in DEEPSEEK_API_KEY and JWT_SECRET
docker compose up -d

API available at http://localhost:8000 Docs at http://localhost:8000/docs

Without Docker

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Production Backend

The backend is hosted on AWS EC2 (ap-south-1, t3.micro, Ubuntu 24.04), running via Docker Compose with PostgreSQL.

Connection details and SSH access are kept private. Ask a team member for access.

Live at https://ella.navgurukul.org — HTTPS via Let’s Encrypt on nginx.

Deploying updates to EC2

SSH into the server using the team’s shared key (ask a team member), then:

# Pull latest code and restart
cd ~/ella_flutter && git pull
cd backend && docker compose down && docker compose up -d

API Overview

18 endpoints total across 6 routers.

Category	Endpoints	Flutter integrated
Auth	`POST /auth/anonymous`	✅
Users	`GET /users/me`, `PUT /users/me`, `PUT /users/me/settings`	✅ profile, ❌ settings
Placements	`POST /placements`, `GET /placements/latest`, `GET /placements`	✅ save + latest
Conversations	`POST`, `GET`, `GET /:id`, `PUT /:id/complete`, `POST /:id/messages`, `GET /:id/messages`	❌ not yet
LLM (backend proxy)	`POST /llm/placement-turn`, `/conversation-turn`, `/conversation-starter`, `/session-analysis`	❌ app calls DeepSeek directly
Progress	`GET /progress/summary`	❌ not yet

Full endpoint reference: backend/README.md

Branches

Branch	Purpose
`main`	Stable
`feature/integration`	Latest working code
`feature/backend-integration`	Backend API wiring (active)

Key Services (Flutter)

Service	File	Purpose
`ApiService`	`lib/services/api_service.dart`	All backend HTTP calls + JWT auth
`LlmService`	`lib/services/llm_service.dart`	Direct DeepSeek/OpenAI calls
`NativeSttService`	`lib/services/native_stt_service.dart`	Android native STT
`TtsManager`	`lib/services/tts_manager.dart`	Piper + system TTS
`UserPrefsService`	`lib/services/user_prefs_service.dart`	Local SharedPreferences

​Ella — Voice-First English Learning App

​What Ella Does

​Who It’s For

​Tech Stack

​Design Prototype

​Notion Docs

​For Claude / New Contributors — Read This First

​Project Structure

​Running the Frontend

​Running the Backend

​With Docker (recommended)

​Without Docker

​Production Backend

​Deploying updates to EC2

​API Overview

​Branches

​Key Services (Flutter)