<!-- Generated by Code Factory | Spec: SPEC-20260319-001 | Date: 2026-03-19 -->

🔤 Phonics App

A kids phonics learning app built with Expo (React Native), Node.js, and PostgreSQL. Runs natively on iOS and Android, and in-browser on mobile/desktop — single codebase.

Quick Start

Prerequisites

• Docker + Docker Compose
• Node.js 22+ (for local development)
• npm 10+

First Run

# 1. Clone the repo
git clone <repo-url>
cd phonics-app

# 2. Set up environment
cp .env.example .env
# Edit .env with your preferred DB credentials

# 3. Start all services
docker-compose up --build

The app will be available at:

• Web App: http://localhost:8080
• API: http://localhost:8080/api
• Health check: http://localhost:8080/api/health

Dev Mode (hot reload)

docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

Direct API access at http://localhost:3001 in dev mode.

---

Project Structure

phonics-app/
├── apps/mobile/          # Expo app (iOS, Android, Web)
├── services/api/         # Node.js/Express REST API
├── packages/shared/      # Shared TypeScript types
├── db/                   # SQL schema + seed data
├── nginx/                # Reverse proxy config
├── docker-compose.yml    # Production-like local stack
└── docker-compose.dev.yml  # Dev overrides

Services

Service	Image	Port (internal)	Purpose
db	postgres:16-alpine	5432	PostgreSQL database
api	node:22-alpine	3001	REST API + audio files
web	nginx:alpine	80	Expo web build
proxy	nginx:alpine	8080	Reverse proxy

API Endpoints

Method	Path	Description
GET	/api/health	Health check
GET	/api/lessons	List all lessons
GET	/api/lessons/:id	Get lesson by ID
GET	/api/progress/:userId	Get user progress
POST	/api/progress/:userId	Update user progress
GET	/api/audio/:filename	Serve audio file

Phonics Content

Phase 1 covers:

• 26 letter sounds: a–z
• 10 digraphs/vowel teams: sh, ch, th, ph, wh, ai, oa, ee, ou, oy

Development

# Install all workspace dependencies
npm install

# Type check all packages
npm run typecheck

# Run all tests
npm run test

# Lint all packages
npm run lint

Environment Variables

See .env.example for all required variables. Never commit .env to git.

License

Private — all rights reserved.