Thrivify - AI-Powered Language Learning Platform

A multi-platform language learning application that uses AI-driven conversations to help users practice and improve their language skills. This monorepo contains a React Native mobile app, Next.js web application, and standalone WebSocket server for real-time communication.

🎯 What is Thrivify?

Thrivify is an AI-powered language learning platform where users practice conversations with AI tutors that adapt to their learning level (CEFR framework). The platform emphasizes natural dialogue practice with real-time feedback and corrections.

Core Features:

• AI Conversation Partners: Two specialized OpenAI assistants ("Thrivify" and "Language Expert") provide conversational practice
• CEFR Level Adaptation: AI adjusts difficulty based on user's language proficiency (A1-C2)
• Structured Lessons: Progressive language lessons with training data storage
• Real-time Communication: WebSocket-based chat across mobile and web platforms
• Language Analysis: Syntax parsing, vocabulary filtering, and correction tracking
• Multi-platform: Native mobile apps (iOS/Android via Expo) and responsive web interface
• Offline-First Mobile: Realm database enables offline functionality with eventual sync

📱 Tech Stack

Mobile App (packages/mobile-app)

• Framework: Expo 49 / React Native 0.72.6
• State Management: Jotai atoms + React Query (TanStack Query)
• Local Database: Realm for offline-first data storage
• Navigation: React Navigation 6.x (Native Stack, Bottom Tabs)
• UI Components: React Native Paper, Styled Components, Flash List
• Chat Interface: React Native Gifted Chat
• Speech: Expo Speech (TTS), React Native Voice (STT)
• Animations: React Native Reanimated, Lottie
• Storage: React Native MMKV (fast key-value storage)
• Notifications: Expo Notifications
• Language: TypeScript

Web App (packages/web-app)

• Framework: Next.js 14 (Pages Router)
• Database: Azure Cosmos DB
• AI Integration: OpenAI GPT with Assistants API
• Styling: Tailwind CSS
• WebSocket Client: Custom integration
• Authentication: Custom header-based auth (x-install-id)
• Deployment: Docker container to Azure App Service
• Language: TypeScript

WebSocket Server (packages/websocket-server)

• Runtime: Node.js 20.x
• Framework: Express.js + ws library
• Database: Azure Cosmos DB (shared with web-app)
• Real-time: WebSocket server for both mobile and web clients
• Deployment: Docker container to Azure App Service
• Language: TypeScript

Backend (packages/backend)

• Purpose: DynamoDB table definitions (legacy infrastructure)
• Framework: Serverless Framework
• Cloud: AWS (DynamoDB tables only)
• Status: Infrastructure-only, no active Lambda functions
• Note: DynamoDB tables appear unused; all services use Azure Cosmos DB

🏗️ Architecture

Actual System Architecture

┌─────────────────┐         ┌─────────────────┐
│  Mobile App     │         │    Web App      │
│  (React Native) │         │   (Next.js)     │
└────────┬────────┘         └────────┬────────┘
         │                           │
         │ REST API                  │ (Internal)
         │ WebSocket                 │ WebSocket
         │                           │
         ├───────────────────────────┤
         │                           │
┌────────▼────────┐         ┌────────▼────────┐
│   Next.js App   │◄────────┤ WebSocket Server│
│  (API Routes)   │  Query  │  (Express + ws) │
└────────┬────────┘         └────────┬────────┘
         │                           │
         │                           │
         └─────────┬─────────────────┘
                   │
          ┌────────▼────────┐
          │ Azure Cosmos DB │
          │   (thrivify)    │
          └─────────────────┘

Key Components

1. Next.js Web App (packages/web-app)

   • Serves the web interface at add-secret-here
   • Provides REST API endpoints at /api/* that BOTH mobile and web clients use
   • Integrates with OpenAI Assistants API for AI conversations
   • Stores all data in Azure Cosmos DB
   • API endpoints include: user, conversations, thread, message, lesson, language, etc.

2. WebSocket Server (packages/websocket-server)

   • Standalone WebSocket server at add-secret-here
   • Handles real-time messaging for both mobile and web clients
   • Shares Azure Cosmos DB with web-app
   • Validates challenges and manages connection lifecycle

3. Mobile App (packages/mobile-app)

   • Makes HTTP requests to Next.js API routes (not AWS Lambda)
   • Connects to WebSocket server for real-time updates
   • Uses Realm for offline-first local storage
   • Syncs data when connection is available

4. Backend Package (packages/backend)

   • Important: This is NOT an API server
   • Only contains DynamoDB table definitions via Serverless Framework
   • Tables appear to be legacy/unused (all services use Cosmos DB)
   • Has one WebSocket handler file that may be deprecated

🔑 Key Features

Language Learning Features

• ✅ AI-powered conversation practice with 2 specialized assistants
• ✅ CEFR-level adaptive difficulty (A1-C2)
• ✅ Real-time language corrections and feedback
• ✅ Vocabulary filtering and syntax analysis
• ✅ Structured progressive lessons
• ✅ Lesson training data collection
• ✅ Translation practice with training storage
• ✅ Speech-to-text input (mobile)
• ✅ Text-to-speech feedback (mobile)

Technical Features

• ✅ Multi-platform (iOS, Android via Expo, Web via Next.js)
• ✅ Offline-first mobile app (Realm database with sync)
• ✅ Real-time WebSocket communication
• ✅ Azure Cosmos DB for all active services
• ✅ OpenAI GPT Assistants API integration
• ✅ Docker containerization for web services
• ✅ TypeScript throughout (mobile, web, websocket-server)
• ✅ Header-based authentication (x-install-id)
• ✅ Custom language syntax parsing
• ✅ JSON repair utilities for robust AI response handling

🚀 Getting Started

Prerequisites

• Node.js 18.x or later (20.x for websocket-server)
• Yarn package manager
• Expo CLI (npm install -g expo-cli)
• Azure account (for Cosmos DB)
• OpenAI API key
• Docker (for web service deployment)

Mobile App Setup

cd packages/mobile-app

# Install dependencies
yarn install

# iOS specific - install pods
cd ios && pod install && cd ..

# Configure environment
# Edit app.config.ts to point to your API and WebSocket URLs
# Default production URLs:
# - API: add-secret-here/api
# - WebSocket: add-secret-here

# Start Expo development server
yarn start

# Run on iOS
yarn ios

# Run on Android
yarn android

# Type checking
yarn ts:check

# Linting
yarn lint

Web App Setup

cd packages/web-app

# Install dependencies
yarn install

# Configure environment variables
cp .env.example .env.local
# Edit .env.local with:
# - COSMOS_ENDPOINT (Azure Cosmos DB endpoint)
# - COSMOS_KEY (Azure Cosmos DB key)
# - DEFAULT_ASSISTANT_ID (OpenAI Assistant ID for main tutor)
# - LANGUAGE_EXPERT_ASSISTANT_ID (OpenAI Assistant ID for language expert)
# - OPENAI_API_KEY

# Run development server
yarn dev  # starts on http://localhost:3000

# Build for production
yarn build

# Run production server
yarn start

# Build Docker image
docker build -t klyveress .

WebSocket Server Setup

cd packages/websocket-server

# Install dependencies
yarn install

# Build TypeScript
yarn build

# Configure environment variables
cp .env.example .env
# Edit .env with:
# - COSMOS_ENDPOINT
# - COSMOS_KEY
# - PORT (default: 5738)

# Run development (with watch mode)
yarn dev

# Run production
yarn start  # runs compiled JS from dist/

# Build Docker image
docker build -t klyveress-ws .

Backend (Infrastructure Only)

cd packages/backend

# Install dependencies
yarn install

# Note: This package only defines DynamoDB tables
# No API server exists here

# Deploy infrastructure to AWS (if needed)
serverless deploy --stage prod

# The defined tables are:
# - users, conversations, conversation-participants
# - conversation-actions, websocket-connections
# - lessons, lessons-training

📂 Project Structure

thrivify-monorepo/
├── packages/
│   ├── mobile-app/              # Expo/React Native mobile application
│   │   ├── api/                 # API client and REST endpoint wrappers
│   │   │   ├── rest/            # REST API functions (action, lesson, message, etc.)
│   │   │   ├── database/        # Realm database schemas and queries
│   │   │   ├── hooks/           # React Query hooks
│   │   │   └── language/        # Language detection and processing
│   │   ├── app/                 # App entry point
│   │   ├── components/          # Reusable UI components
│   │   ├── state/               # Jotai atoms for global state
│   │   ├── assets/              # Images, fonts
│   │   ├── lottie/              # Lottie animations
│   │   ├── localization/        # i18n translations
│   │   ├── android/             # Android native code
│   │   └── ios/                 # iOS native code
│   │
│   ├── web-app/                 # Next.js web application + API server
│   │   ├── src/
│   │   │   ├── pages/           # Next.js pages
│   │   │   │   ├── api/         # REST API endpoints (shared by mobile & web)
│   │   │   │   │   ├── conversation.ts
│   │   │   │   │   ├── conversations.ts
│   │   │   │   │   ├── message.ts
│   │   │   │   │   ├── thread.ts
│   │   │   │   │   ├── threadMessages.ts
│   │   │   │   │   ├── threadActions.ts
│   │   │   │   │   ├── user.ts
│   │   │   │   │   ├── lesson.ts
│   │   │   │   │   ├── lessons.ts
│   │   │   │   │   ├── language.ts
│   │   │   │   │   └── health/readiness/startup.ts
│   │   │   │   └── index.tsx    # Web app home page
│   │   │   ├── lib/             # Business logic
│   │   │   │   ├── azure.ts     # Cosmos DB client & containers
│   │   │   │   ├── assistants.ts# OpenAI Assistant configurations
│   │   │   │   ├── authenticate.ts # Auth middleware
│   │   │   │   ├── conversation.ts # Conversation logic
│   │   │   │   ├── message.ts   # Message processing
│   │   │   │   ├── action.ts    # User actions
│   │   │   │   ├── aiResponse/  # AI response processing
│   │   │   │   ├── language/    # Language syntax & analysis
│   │   │   │   ├── openai.ts    # OpenAI client
│   │   │   │   └── websocket.ts # WebSocket utilities
│   │   │   └── styles/          # Global CSS
│   │   ├── Dockerfile           # Docker containerization
│   │   └── cosmos-db-deployment.json
│   │
│   ├── websocket-server/        # Standalone WebSocket server
│   │   ├── src/
│   │   │   ├── server.ts        # Express HTTP server
│   │   │   ├── wss.ts           # WebSocket server (ws library)
│   │   │   ├── endpoints.ts     # HTTP endpoints
│   │   │   ├── azure.ts         # Cosmos DB client
│   │   │   ├── config.ts        # Configuration
│   │   │   └── validateChallenge.ts
│   │   ├── dist/                # Compiled JavaScript output
│   │   └── Dockerfile           # Docker containerization
│   │
│   └── backend/                 # Infrastructure definitions only
│       ├── src/
│       │   └── websockets/      # (Legacy) WebSocket handler
│       │       └── connection.js
│       ├── serverless.yml       # DynamoDB table definitions
│       └── buildspec.yml        # AWS CodeBuild config
│
└── README.md                    # This file

🗄️ Database Schema

Azure Cosmos DB (Active - Used by all services)

Database: thrivify

Containers:

• Users: User profiles, install IDs, learning preferences, CEFR levels
• Conversations: Conversation threads with AI assistants
• ConversationParticipants: Maps users to conversations
• ConversationActions: User actions within conversations (typing, messages, etc.)
• WebsocketConnections: Active WebSocket connection tracking
• Lessons: Language lessons content and metadata
• LessonsTraining: Training data collected from lesson interactions
• TranslationsTraining: Translation practice training data

DynamoDB Tables (Legacy - Defined but unused)

The packages/backend/serverless.yml defines these tables, but they appear unused:

• users, conversations, conversation-participants
• conversation-actions, websocket-connections
• lessons, lessons-training

Note: All active services (web-app, websocket-server, mobile-app) use Azure Cosmos DB exclusively.

🤖 OpenAI Assistants

Two specialized AI assistants configured in packages/web-app/src/lib/assistants.ts:

1. Main Assistant ("Thrivify")

• Purpose: General conversation practice in the target language
• Input Parameters: learningLanguage, nativeLanguage, CEFRLevel
• Response Processing: Extracts message and messageLanguage from JSON response
• Use Case: Natural dialogue practice

2. Language Expert Assistant

• Purpose: Topic-based conversation with corrections
• Input Parameters: learningLanguage, CEFRLevel, topic (e.g., "Travel")
• Response Processing: Extracts messageAboutTopic and correctionsMade
• Use Case: Focused practice with explicit feedback

🔒 Security & Configuration

All sensitive credentials managed through environment variables:

Never commit:

• .env, .env.local files
• Azure Cosmos DB connection strings
• OpenAI API keys
• Docker registry credentials

Configuration Requirements:

Web App (packages/web-app):

• COSMOS_ENDPOINT - Azure Cosmos DB endpoint URL
• COSMOS_KEY - Azure Cosmos DB primary key
• DEFAULT_ASSISTANT_ID - OpenAI Assistant ID for main tutor
• LANGUAGE_EXPERT_ASSISTANT_ID - OpenAI Assistant ID for language expert
• OPENAI_API_KEY - OpenAI API key

WebSocket Server (packages/websocket-server):

• COSMOS_ENDPOINT - Azure Cosmos DB endpoint URL
• COSMOS_KEY - Azure Cosmos DB primary key
• PORT - Server port (default: 5738)

Mobile App (packages/mobile-app):

• Configure apiUrl and webSocketUrl in app.config.ts
• Production defaults:
  • API: add-secret-here/api
  • WebSocket: add-secret-here

🌐 Deployment

Web App (Azure App Service)

cd packages/web-app

# Build Docker image
docker build -t klyveress .

# Tag for Azure Container Registry
docker tag klyveress add-secret-here/klyveress:latest

# Push to registry
az acr login --name add-secret-here
docker push add-secret-here/klyveress:latest

# Azure App Service automatically deploys from container registry

WebSocket Server (Azure App Service)

cd packages/websocket-server

# Build Docker image
docker build -t klyveress-ws .

# Tag and push to Azure Container Registry
docker tag klyveress-ws add-secret-here/klyveress-ws:latest
docker push add-secret-here/klyveress-ws:latest

Mobile App

iOS:

1. Update version in app.json
2. Build with EAS: eas build --platform ios
3. Submit to App Store Connect

Android:

1. Update version in app.json
2. Build with EAS: eas build --platform android
3. Submit to Google Play Console

Expo Development:

cd packages/mobile-app
yarn start  # Opens Expo Dev Tools

📝 API Endpoints

The Next.js web app provides REST API endpoints at /api/* used by BOTH mobile and web clients:

User Management

• POST /api/user - Create/update user profile
• GET /api/user - Get user profile

Conversations

• GET /api/conversations - List user's conversations
• POST /api/conversation - Create new conversation
• DELETE /api/conversation - Delete conversation
• PATCH /api/conversation - Update conversation settings

Threads & Messages (OpenAI Assistants)

• POST /api/thread - Create OpenAI thread
• GET /api/threadMessages - Get messages in a thread
• POST /api/message - Send message to AI assistant
• PATCH /api/message - Analyze message for vocabulary
• GET /api/threadActions - Get thread actions

Lessons

• GET /api/lessons - List available lessons
• GET /api/lesson - Get specific lesson
• POST /api/lesson - Create/update lesson
• PATCH /api/lesson - Update lesson progress

Language Analysis

• POST /api/language - Analyze language syntax and vocabulary

Health Checks

• GET /api/health - Health check
• GET /api/readiness - Readiness probe
• GET /api/startup - Startup probe

🛠️ Development

Running Tests

# Mobile app
cd packages/mobile-app
# (No tests configured yet)

# Web app
cd packages/web-app
# (No tests configured yet)

# Backend
cd packages/backend
yarn test

Type Checking

# Mobile app
cd packages/mobile-app
yarn ts:check

# Web app (automatically checked during build)
cd packages/web-app
yarn build

# Backend
cd packages/backend
yarn type-check

Code Formatting

# Any package
yarn format  # Prettier
yarn lint    # ESLint

Finding Dead Code

# Mobile app
cd packages/mobile-app
yarn find-deadcode  # ts-prune

🌟 Architecture Insights

Key Design Decisions

1. Unified API Layer: Next.js API routes serve both mobile and web clients, avoiding duplication
2. Separate WebSocket Server: Dedicated Express+ws server optimized for real-time messaging
3. Azure-First: All active services use Azure Cosmos DB (DynamoDB tables are legacy)
4. Offline-First Mobile: Realm database enables mobile app to work without connectivity
5. AI Assistants Pattern: OpenAI Assistants API maintains conversation context across sessions
6. Header-Based Auth: Simple x-install-id header authentication for cross-platform compatibility
7. JSON Repair: Uses jsonrepair library to handle malformed AI responses gracefully
8. CEFR Framework: Standardized language proficiency levels (A1-C2) for adaptive difficulty

Common Misconceptions (from old README)

❌ "AWS Lambda Backend API" - The backend package only defines infrastructure, no Lambda functions exist ✅ Reality: Next.js API routes serve as the REST API

❌ "Dual Database Architecture (DynamoDB + Cosmos)" - DynamoDB tables are defined but unused ✅ Reality: Only Azure Cosmos DB is actively used by all services

❌ "Mobile connects to AWS services" - Mobile app doesn't use AWS at all ✅ Reality: Mobile connects to Next.js (Azure) and WebSocket server (Azure)

📝 License

Private - All rights reserved

---

Note: This is a portfolio project showcasing multi-platform language learning technology, AI integration via OpenAI Assistants API, real-time WebSocket communication, and full-stack TypeScript development. Production credentials have been sanitized for security.