madava/playground
1
0
Fork 0
Code Pull Requests Actions Releases Activity

Add dockerized app and infra scaffolding

Browse Source
This commit is contained in:
Madava
2025-11-26 06:49:58 +01:00
parent 575c02431e
commit 01ebc23e3f
17 changed files with 2426 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
README.md
View File

@@ -71,114 +71,3 @@
| **⭐ 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
```bash
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.
├── .gitattributes # Controls Git’s handling of files across platforms (e.g. normalizing line endings with * text=auto), and can force certain files to be treated as binary or configure diff/merge drivers.
│
├── .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.
```