Product Description

avaaz.ai is a mobile and web application featuring a motivating conversational AI tutor powered by advanced agentic capabilities. It teaches oral language skills through structured, interactive lessons that adapt to each student’s pace and performance. The core goal is to help students speak new languages confidently to pass the B2 oral proficiency exam.

1. Features

1. Voice-First Conversational Engine — Students engage in ultra-low-latency speech-to-speech interaction with the AI Tutor, enabling natural dialogue and instant corrective feedback using speech, text, and visuals.
2. CEFR-B2 Aligned Curriculum with Real-Time AI Practice — A full CEFR-based speaking progression up to B2, seamlessly integrated with adaptive AI conversation to bridge passive knowledge and active speaking skills.
3. Immigrant-Focused Real-Life Scenarios — Lessons target real-world contexts relevant to immigrants, such as workplace, healthcare, school, or daily interactions, enhancing integration and confidence in practical use.
4. Mock Oral Exam Mode — Simulates B2 oral exams and citizenship interviews with timed prompts, rubrics, and examiner-style feedback to build test readiness.
5. Multilingual Scaffolding and Integrated Translation — Learners receive UI support, bilingual explanations, and on-demand translations in their native language, helping low-confidence speakers stay engaged.
6. Comprehensive Speaking Feedback — Beyond pronunciation and grammar, learners get targeted insights on fluency, phrasing, coherence, and vocabulary range, aligned with B2 standards.
7. Accent and Cultural Adaptation — Lessons reflect local dialects and cultural etiquette relevant to the learner’s destination country, supporting realistic and socially appropriate speech.
8. Immersive Role-Plays with Visual Cues — Speaking simulations are enhanced with contextual images (e.g. menus, documents, locations) to deepen realism and task-based practice.
9. Gamified Progress and Motivation — Daily speaking challenges, streak rewards, and level badges reinforce habit formation and learning consistency.
10. Post-Session Performance Summaries — After each session, learners receive a concise report of strengths, errors, and suggested improvements to reinforce progress.
11. Customizable AI Tutor Voices — Learners can choose from various voice options with different genders or regional accents to diversify listening practice and personalize interaction.
12. Cross-Device Learning Continuity — Seamless synchronization ensures progress tracking and learning state remain consistent across mobile and web platforms.

2. Student & AI Tutor Interactions (English → Norwegian Bokmål)

2.1 Real-Time Conversational Flow

Scenario: A beginner is learning everyday greetings.

AI Tutor (in Norwegian): “Hei! Hvordan går det?”
Student: “Uh… I think that means, ‘How are you?’”
AI Tutor: “Exactly! You can answer: Jeg har det bra — that means ‘I’m doing well.’ Try it: Jeg har det bra.”
Student: “Jeg har det bra.”
AI Tutor: “Flott! Literally, it means ‘I have it good.’ Norwegians use that to say they’re fine.”

Benefit: The AI provides instant translation and cultural context, helping English speakers grasp meaning and tone through natural conversation.

2.2 Adaptive Pronunciation, Fluency, and Grammar Support

Scenario: The learner practices sentence structure and pronunciation.

AI Tutor: “Let’s say: Jeg bor i Oslo — ‘I live in Oslo.’”
Student: “Jeg bor på Oslo.”
AI Tutor: “Almost right! We say i Oslo, not på Oslo. I means ‘in,’ while på means ‘on.’ Try again: Jeg bor i Oslo.”
Student: “Jeg bor i Oslo.”
AI Tutor: “Perfekt! Now, about pronunciation — it’s Oslo, not Osh-lo. The s is soft. Listen: Oslo.”
Student: “Oslo.”
AI Tutor: “Bra! That sounded natural.”

Benefit: The AI corrects grammar and pronunciation simultaneously, giving immediate, native-level feedback tailored to English-speaking learners.

2.3 Scenario-Based Oral Practice

Scenario: The learner prepares for a B2-level job interview.

AI Tutor: “Du er på et jobbintervju. Spørsmålet er: Hvorfor vil du jobbe her? — ‘Why do you want to work here?’”
Student: “Fordi jeg liker din selskap.”
AI Tutor: “Good start! In Norwegian, we say firmaet ditt instead of din selskap. Try: Fordi jeg liker firmaet ditt og arbeidsmiljøet her. — ‘Because I like your company and the work environment here.’”
Student: “Fordi jeg liker firmaet ditt og arbeidsmiljøet her.”
AI Tutor: “Veldig bra! That sounded confident and natural.”

Benefit: The learner rehearses authentic B2-level oral exam tasks and professional interactions with context-sensitive correction and adaptive feedback.

3. Pricing Plans

Plan	Hours	NOK	Purpose
First Light	1	Gratis	A taste of the experience - no pressure, no card required.
Spark	5	kr 999	A short, flexible plan to get started or focus on specific skills.
Glow	15	kr 1 999	Great for consistent improvement and practicing real conversations.
⭐ Shine (Recommended)	50	kr 5 999	The sweet spot for building natural fluency and confidence.
Radiance	200	kr 17 999	Designed for dedicated learners seeking transformation.

4. Project Structure

avaaz.ai/
├── .dockerignore                    # Specifies files and directories to exclude from Docker builds, such as .git, node_modules, and build artifacts, to optimize image sizes.
├── .gitignore                       # Lists files and patterns to ignore in Git, including .env, __pycache__, node_modules, and logs, preventing sensitive or temporary files from being committed.
│
├── .env.example                     # Template for environment variables, showing required keys like DATABASE_URL, GEMINI_API_KEY, LIVEKIT_API_KEY without actual values.
├── docker-compose.dev.yml           # Docker Compose file for development environment: defines services for local frontend, backend, postgres, livekit with volume mounts for hot-reloading.
├── docker-compose.prod.yml          # Docker Compose file for production: defines services for caddy, gitea (if integrated), frontend, backend, postgres, livekit with optimized settings and no volumes for code.
├── README.md                        # Project overview: includes setup instructions, architecture diagram (embed the provided Mermaid), contribution guidelines, and deployment steps.
│
├── .gitea/                          # Directory for Gitea-specific configurations, as the repo is hosted on Gitea.
│   └── workflows/                   # Contains YAML files for Gitea Actions workflows, enabling CI/CD pipelines.
│       ├── ci.yml                   # Workflow for continuous integration: runs tests, linting (Ruff), type checks, and builds on pull requests or pushes.
│       └── cd.yml                   # Workflow for continuous deployment: triggers builds and deploys Docker images to the VPS on merges to main.
│
├── .vscode/                         # Editor configuration for VS Code to standardize the development environment for all contributors.
│   ├── extensions.json              # Recommends VS Code extensions (e.g. Python, ESLint, Docker, GitLens) so developers get linting, formatting, and container tooling out of the box.
│   └── settings.json                # Workspace-level VS Code settings: formatter on save, path aliases, Python/TypeScript language server settings, lint integration (Ruff, ESLint), and file exclusions.
│
├── backend/                         # Root for the FastAPI backend, following Python best practices for scalable applications (inspired by FastAPI's "Bigger Applications" guide).
│   ├── Dockerfile                   # Builds the backend container: installs UV, copies pyproject.toml, syncs dependencies, copies source code, sets entrypoint to Gunicorn/Uvicorn.
│   ├── pyproject.toml               # Project metadata and dependencies: uses UV for dependency management, specifies FastAPI, SQLAlchemy, Pydantic, LiveKit-Agent, etc.; includes [tool.uv], [tool.ruff] sections for config.
│   ├── uv.lock                      # Lockfile generated by UV, ensuring reproducible dependencies across environments.
│   ├── ruff.toml                    # Configuration for Ruff linter and formatter (can be in pyproject.toml): sets rules for Python code style, ignoring certain errors if needed.
│   ├── alembic.ini                  # Configuration for Alembic migrations: points to SQLAlchemy URL and script location.
│   ├── alembic/                     # Directory for database migrations using Alembic, integrated with SQLAlchemy.
│   │   ├── env.py                   # Alembic environment script: sets up the migration context with SQLAlchemy models and pgvector support.
│   │   ├── script.py.mako           # Template for generating migration scripts.
│   │   └── versions/                # Auto-generated migration files: each represents a database schema change, e.g., create_tables.py.
│   ├── src/                         # Source code package: keeps business logic isolated, importable as 'from src import ...'.
│   │   ├── __init__.py              # Makes src a package.
│   │   ├── main.py                  # FastAPI app entrypoint: initializes app, includes routers, sets up middleware, connects to Gemini Live via prompts.
│   │   ├── config.py                # Application settings: uses Pydantic-settings to load from .env, e.g., DB_URL, API keys for Gemini, LiveKit, Stripe (for pricing plans).
│   │   ├── api/                     # API-related modules: organizes endpoints and dependencies.
│   │   │   ├── __init__.py          # Package init.
│   │   │   ├── dependencies.py      # Global dependencies: e.g., current_user via FastAPI Users, database session.
│   │   │   └── v1/                  # Versioned API: allows future versioning without breaking changes.
│   │   │       └── routers/         # API routers: modular endpoints.
│   │   │           ├── auth.py      # Handles authentication: uses FastAPI Users for JWT/OAuth, user registration/login.
│   │   │           ├── users.py     # User management: progress tracking, plan subscriptions.
│   │   │           ├── lessons.py   # Lesson endpoints: structured oral language lessons, progress tracking.
│   │   │           ├── chat.py      # Integration with LiveKit and Gemini: handles conversational AI tutor sessions.
│   │   │           └── documents.py # Document upload and processing: endpoints for file uploads, using Docling for parsing and semantic search prep.
│   │   ├── core/                    # Core utilities: shared across the app.
│   │   │   ├── __init__.py          # Package init.
│   │   │   └── security.py          # Security functions: hashing, JWT handling via FastAPI Users.
│   │   ├── db/                      # Database layer: SQLAlchemy setup with pgvector for vector embeddings (e.g., for AI tutor memory).
│   │   │   ├── __init__.py          # Package init.
│   │   │   ├── base.py              # Base model class for SQLAlchemy declarative base.
│   │   │   ├── session.py           # Database session management: async session maker.
│   │   │   └── models/              # SQLAlchemy models.
│   │   │       ├── __init__.py      # Exports all models.
│   │   │       ├── user.py          # User model: includes fields for progress, plan, proficiency.
│   │   │       ├── lesson.py        # Lesson and session models: tracks user interactions, B2 exam prep.
│   │   │       └── document.py      # Document chunk model: for semantic search, with text, metadata, embedding (pgvector).
│   │   ├── schemas/                 # Pydantic schemas: for API validation and serialization.
│   │   │   ├── __init__.py          # Exports schemas.
│   │   │   ├── user.py              # User schemas: create, read, update.
│   │   │   ├── lesson.py            # Lesson schemas: input/output for AI interactions.
│   │   │   └── document.py          # Document schemas: for upload responses and search queries.
│   │   └── services/                # Business logic services: decoupled from API.
│   │       ├── __init__.py          # Package init.
│   │       ├── llm.py               # Gemini Live integration: prompt engineering for conversational tutor.
│   │       ├── payment.py           # Handles pricing plans: integrates with Stripe for subscriptions (Spark, Glow, etc.).
│   │       └── document.py          # Docling processing: parses files, chunks, embeds (via Gemini), stores for semantic search.
│   └── tests/                       # Unit and integration tests: uses pytest, Hypothesis for property-based testing, httpx for API testing.
│       ├── __init__.py              # Package init.
│       ├── conftest.py              # Pytest fixtures: e.g., test database, mock Gemini.
│       └── test_users.py            # Example test file: tests user endpoints.
│
├── frontend/                        # Root for Next.js frontend and PWA, following Next.js app router best practices (2025 standards: improved SSR, layouts).
│   ├── Dockerfile                   # Builds the frontend container: installs dependencies, builds Next.js, serves with Node.
│   ├── .eslintrc.json               # ESLint configuration: extends next/core-web-vitals, adds rules for code quality.
│   ├── next.config.js               # Next.js config: enables PWA, images optimization, API routes if needed.
│   ├── package.json                 # Node dependencies: includes next, react, @livekit/client for WebRTC, axios or fetch for API calls.
│   ├── package-lock.json            # Lockfile for reproducible npm installs.
│   ├── tsconfig.json                # TypeScript config: targets ES2022, includes paths for components.
│   ├── app/                         # App router directory: pages, layouts, loading states.
│   │   ├── globals.css              # Global styles: Tailwind or CSS modules.
│   │   ├── layout.tsx               # Root layout: includes providers, navigation.
│   │   ├── page.tsx                 # Home page: landing for avaaz.ai.
│   │   └── components/              # Reusable UI components.
│   │       ├── ChatInterface.tsx    # Component for conversational tutor using LiveKit WebRTC.
│   │       └── ProgressTracker.tsx  # Tracks user progress toward B2 exam.
│   ├── lib/                         # Utility functions: API clients, hooks.
│   │   └── api.ts                   # API client: typed fetches to backend endpoints.
│   └── public/                      # Static assets.
│       ├── favicon.ico              # Site icon.
│       └── manifest.json            # PWA manifest: for mobile app-like experience.
│
├── infra/                           # Infrastructure configurations: Dockerfiles and configs for supporting services, keeping them separate for scalability.
│   ├── caddy/                       # Caddy reverse proxy setup.
│   │   ├── Dockerfile               # Extends official Caddy image, copies Caddyfile.
│   │   └── Caddyfile                # Caddy config: routes www.avaaz.ai to frontend, api.avaaz.ai to backend, WSS to LiveKit; auto HTTPS.
│   ├── gitea/                       # Gitea git server (added for customization if needed; otherwise use official image directly in Compose).
│   │   ├── Dockerfile               # Optional: Extends official Gitea image, copies custom config for Actions integration.
│   │   └── app.ini                  # Gitea config: sets up server, database, Actions runner.
│   ├── livekit/                     # LiveKit server for real-time audio/video in tutor sessions.
│   │   ├── Dockerfile               # Extends official LiveKit image, copies config.
│   │   └── livekit.yaml             # LiveKit config: API keys, room settings, agent integration for AI tutor.
│   └── postgres/                    # PostgreSQL with pgvector.
│       ├── Dockerfile               # Extends postgres image, installs pgvector extension.
│       └── init/                    # Initialization scripts.
│           └── 00-pgvector.sql      # SQL to create pgvector extension on db init.
│
└── docs/                            # Documentation: architecture, APIs, etc.
    └── architecture.md              # Detailed system explanation, including the provided Mermaid diagram.