Supabase

.github/workflows/lint.yml

@@ -21,14 +21,28 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: '20'
-          cache: 'npm'
 
-      - name: Install dependencies
+      - name: Install backend dependencies
+        working-directory: ./backend
         run: npm ci
 
-      - name: Run ESLint
+      - name: Install frontend dependencies
+        working-directory: ./frontend
+        run: npm ci
+
+      - name: Run ESLint (backend)
+        working-directory: ./backend
+        run: npm run lint
+
+      - name: Run ESLint (frontend)
+        working-directory: ./frontend
         run: npm run lint
 
-      - name: Check Prettier formatting
+      - name: Check Prettier formatting (backend)
+        working-directory: ./backend
+        run: npm run format:check
+
+      - name: Check Prettier formatting (frontend)
+        working-directory: ./frontend
         run: npm run format:check
 

.gitignore

@@ -143,3 +143,8 @@ backend/audio/
 .DS_Store
 CLAUDE.md
 templates/
+.claude
+
+# Deployment files
+deploy/
+.gcloudignore

.prettierrc.json

@@ -8,3 +8,4 @@
   "arrowParens": "always",
   "endOfLine": "lf"
 }
+

CONTRIBUTING.md

@@ -33,6 +33,7 @@ Thank you for your interest in contributing to the Language Learning App! This d
 
    ```bash
    INWORLD_API_KEY=your_api_key_here
+   ASSEMBLY_AI_API_KEY=your_api_key_here
    ```
 
 5. **Verify the setup**:

README.md

@@ -1,18 +1,20 @@
-# Language Learning - Aprendemo
+# Inworld Language Tutor
 
 [![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Powered by Inworld AI](https://img.shields.io/badge/Powered_by-Inworld_AI-orange)](https://inworld.ai/runtime)
 [![Documentation](https://img.shields.io/badge/Documentation-Read_Docs-blue)](https://docs.inworld.ai/docs/node/overview)
 [![Model Providers](https://img.shields.io/badge/Model_Providers-See_Models-purple)](https://docs.inworld.ai/docs/models#llm)
 
-A Node.js app where you can learn Spanish through conversation and flashcard studying, powered by Inworld AI Runtime. "Aprendemo" combines "Aprender" (Spanish for "to learn") with "demo" - it's both a language learning tool and a demonstration of the Inworld Runtime Node.js SDK.
+A conversational language learning app powered by Inworld AI Runtime. Practice speaking with an AI tutor, get real-time feedback on your responses, and build vocabulary with auto-generated flashcards.
 
 ![App](screenshot.jpg)
 
 ## Prerequisites
 
 - Node.js (v20 or higher)
+- npm
 - An Inworld AI account and API key
+- An AssemblyAI account and API key (for speech-to-text)
 
 ## Get Started
 
@@ -25,64 +27,170 @@ cd language-learning-node
 
 ### Step 2: Install Dependencies
 
+
+Frontend:
+```bash
+cd frontend
+npm install
+```
+
+Backend:
 ```bash
+cd backend
 npm install
 ```
 
 ### Step 3: Configure Environment Variables
 
-Create a `.env` file in the root directory:
+Create a `.env` file in the /backend directory:
 
 ```bash
-INWORLD_API_KEY=your_api_key_here
+INWORLD_API_KEY=your_inworld_base64_key
+ASSEMBLY_AI_API_KEY=your_assemblyai_key
 ```
 
-Get your Base64 API key from the [Inworld Portal](https://platform.inworld.ai/).
+| Service        | Get Key From                                        | Purpose                           |
+| -------------- | --------------------------------------------------- | --------------------------------- |
+| **Inworld**    | [platform.inworld.ai](https://platform.inworld.ai/) | AI conversations (Base64 API key) |
+| **AssemblyAI** | [assemblyai.com](https://www.assemblyai.com/)       | Speech-to-text                    |
 
 ### Step 4: Run the Application
 
-For development:
+**For development** (with auto-reload on file changes):
 
+In frontend dir:
 ```bash
 npm run dev
 ```
 
-For production:
+In backend dir:
+```bash
+npm run dev
+```
+
+Open [http://localhost:5173](http://localhost:5173)
+
+### Step 5 (Optional): Set Up Supabase for Auth & Memory
+
+Without Supabase, the app works in anonymous mode using localStorage.
+
+**a) Create a Supabase project** at [supabase.com](https://supabase.com)
+
+**b) Push the database schema:**
+
+```bash
+npx supabase login
+npx supabase link --project-ref YOUR_PROJECT_REF
+npx supabase db push
+```
+
+This creates all tables, indexes, RLS policies, and the `match_memories` function for semantic search.
+
+Find your project ref in the Supabase dashboard URL: `supabase.com/dashboard/project/YOUR_PROJECT_REF`
+
+**c) Add Supabase variables to `.env` (backend):**
 
 ```bash
-npm run build
-npm start
+SUPABASE_URL=https://YOUR_PROJECT.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
 ```
 
+**d) Create `frontend/.env.local`:**
+
+```bash
+VITE_SUPABASE_URL=https://YOUR_PROJECT.supabase.co
+VITE_SUPABASE_PUBLISHABLE_KEY=your_anon_key
+```
+
+Find these in: Supabase Dashboard > Settings > API
+
 ## Repo Structure
 
 ```
 language-learning-node/
 ├── backend/
-│   ├── graphs/               # Graph definitions
-│   │   ├── conversation-graph.ts
-│   │   ├── flashcard-graph.ts
-│   │   └── introduction-state-graph.ts
-│   ├── helpers/              # Helper utilities
-│   │   ├── anki-exporter.ts
-│   │   ├── audio-buffer.ts
-│   │   ├── audio-processor.ts
-│   │   ├── flashcard-processor.ts
-│   │   ├── introduction-state-processor.ts
-│   │   ├── prompt-templates.ts
-│   │   └── silero-vad.ts
-│   ├── models/               # AI models
-│   │   └── silero_vad.onnx
-│   └── server.ts             # Backend server
-├── frontend/                 # Frontend application
-│   ├── js/
-│   ├── styles/
-│   └── index.html
-├── flashcard-graph.json      # Flashcard configuration
-├── package.json              # Dependencies
-└── LICENSE                   # MIT License
+│   ├── src/
+│   │   ├── __tests__/        # Backend unit tests
+│   │   ├── config/           # Language & server configuration
+│   │   ├── graphs/           # Inworld Runtime conversation graphs
+│   │   │   ├── configs/      # Graph JSON configurations
+│   │   │   └── nodes/        # Custom graph nodes
+│   │   ├── helpers/          # Audio utils, connection management
+│   │   ├── prompts/          # Nunjucks prompt templates
+│   │   ├── services/         # Server components
+│   │   ├── utils/            # Logger
+│   │   └── server.ts         # Entry point
+│   ├── .env                  # Backend environment variables
+│   └── vitest.config.ts      # Backend test config
+├── frontend/
+│   ├── src/
+│   │   ├── __tests__/        # Frontend unit tests
+│   │   ├── components/       # React components
+│   │   ├── context/          # App state & auth
+│   │   ├── hooks/            # Custom React hooks
+│   │   ├── services/         # WebSocket client, audio, storage
+│   │   ├── styles/           # CSS
+│   │   └── types/            # TypeScript types
+│   ├── .env.local            # Frontend environment variables
+│   └── vitest.config.ts      # Frontend test config
+├── supabase/
+│   └── migrations/           # Database schema
+└── deploy/                   # Deployment configurations
+```
+
+## Architecture
+
+The app uses a real-time audio streaming architecture:
+
+1. **Frontend** captures microphone audio and streams it via WebSocket
+2. **Backend** processes audio through an Inworld Runtime graph:
+   - AssemblyAI handles speech-to-text with voice activity detection
+   - LLM generates contextual responses in the target language
+   - TTS converts responses back to audio
+3. **Flashcards** are auto-generated from conversation vocabulary
+4. **Response feedback** provides grammar and usage corrections
+
+## Memory System
+
+When Supabase is configured, the app stores and retrieves user memories using semantic search:
+
+- **Automatic memory creation**: Every few conversation turns, the system extracts memorable facts
+- **Semantic retrieval**: Relevant memories are retrieved using vector similarity search (pgvector)
+- **Personalized responses**: The AI uses retrieved memories to personalize conversations
+
+Memory types:
+
+- `learning_progress`: Vocabulary struggles, grammar patterns, learning achievements
+- `personal_context`: Interests, goals, preferences shared by the user
+
+Without Supabase, the app works in anonymous mode using localStorage (no memory persistence).
+
+## Environment Variables Reference
+
+| Variable                    | Required | Description                                                        |
+| --------------------------- | -------- | ------------------------------------------------------------------ |
+| `INWORLD_API_KEY`           | Yes      | Inworld AI Base64 API key                                          |
+| `ASSEMBLY_AI_API_KEY`       | Yes      | AssemblyAI API key                                                 |
+| `PORT`                      | No       | Server port (default: 3000)                                        |
+| `LOG_LEVEL`                 | No       | `trace`, `debug`, `info`, `warn`, `error`, `fatal` (default: info) |
+| `NODE_ENV`                  | No       | `development` or `production`                                      |
+| `ASSEMBLY_AI_EAGERNESS`     | No       | Turn detection: `low`, `medium`, `high` (default: high)            |
+| `SUPABASE_URL`              | No       | Supabase project URL (enables memory feature)                      |
+| `SUPABASE_SERVICE_ROLE_KEY` | No       | Supabase service role key (for backend memory storage)             |
+
+## Testing
+
+Run the test suite to verify core functionality:
+
+```bash
+npm test              # Run all tests
+npm run test:backend  # Backend tests only
+npm run test:frontend # Frontend tests only
+npm run test:watch    # Watch mode for backend
 ```
 
+Tests cover critical paths: audio conversion, language configuration, storage persistence, and flashcard deduplication.
+
 ## Troubleshooting
 
 **Bug Reports**: [GitHub Issues](https://github.com/inworld-ai/language-learning-node/issues)

backend/.env.example

@@ -0,0 +1,5 @@
+INWORLD_API_KEY=
+ASSEMBLY_AI_API_KEY=
+
+SUPABASE_URL=
+SUPABASE_SERVICE_ROLE_KEY=

eslint.config.mjs → backend/eslint.config.mjs

@@ -18,7 +18,7 @@ export default [
     languageOptions: {
       parser: tseslint.parser,
       parserOptions: {
-        project: true,
+        project: './tsconfig.eslint.json',
         tsconfigRootDir: __dirname,
       },
     },