Application Overview: LinguFlow
LinguFlow is a modern, keyboard-driven language learning platform designed for high-efficiency study and certification exam simulation.
π Key Featuresβ
-
Spaced Repetition System (SRS):
- Powered by an optimized implementation of the SuperMemo-2 (SM-2) algorithm.
- Custom card scheduling based on review ratings (Again, Hard, Good, Easy), target interval multipliers, and ease factors.
-
Exam Simulator & Practice:
- Realistic exam simulator supporting major international language certifications: TOEIC, IELTS, HSK, and JLPT.
- Version-pinned attempts, section clocks, multi-scale scores, plus a separate practice mode (bank/exam draws).
- TOEIC Listening (Parts 1β4): shared stimulus blocks + tape player. See TOEIC Listening Items and Question & Exam Design.
-
Deck & Card Management:
- Rich Markdown support for card prompt text and answer explanations (
MarkdownRenderer). - Media upload support (audio clips and flashcard images) powered by object storage.
- Rich Markdown support for card prompt text and answer explanations (
-
Optional AI tutor (registered users):
- Explain a flipped flashcard or a completed exam answer.
- Generate new bank questions from a topic (async job; never auto-attached to an exam).
- Request an opt-in, non-spoiling hint during a live sitting (
H). - See AI Features and AI Service Layer.
-
Retro-Arcade Pixel Design System:
- Unique distraction-free aesthetic with custom pixel framing (
PixelFrame), IBM Plex typography, and 8-color arcade palette tokens. - Pure CSS custom properties integrated into Tailwind utilities.
- Unique distraction-free aesthetic with custom pixel framing (
ποΈ Technology Stackβ
| Layer | Technologies |
|---|---|
| Frontend | Vue 3 (Composition API <script setup>), TypeScript, Vite, TailwindCSS, Pinia, Marked, DOMPurify |
| Backend | Python 3.12, FastAPI, Uvicorn, Pydantic Settings v2, Python-Jose (JWT), Passlib (bcrypt) |
| Database | PostgreSQL 16, AsyncPG, SQLAlchemy 2.0 (Asyncio), Alembic Migrations |
| Storage | Cloudflare R2 (S3-compatible object storage via aioboto3) |
π Repository Structureβ
lingu-flow/
βββ backend/ # Python FastAPI Backend
β βββ alembic/ # Database migration scripts
β βββ app/
β β βββ core/ # Auth & security primitives
β β βββ models/ # SQLAlchemy Declarative Models
β β βββ routers/ # FastAPI endpoints (auth, cards, assessment_*, ai, health, media, β¦)
β β βββ schemas/ # Pydantic Request/Response validation schemas
β β βββ services/ # Business logic, assessment/, AI client, R2 helper
β β βββ config.py # Application settings (env validation)
β β βββ database.py # Async engine & session lifecycle
β β βββ main.py # FastAPI application entry point & CORS
β βββ tests/ # Pytest async test suite
βββ frontend/ # Vue 3 Frontend
β βββ src/
β β βββ features/ # Domain modules (auth, dashboard, assessment, flashcards, library, admin, β¦)
β β βββ shared/ # Reusable UI primitives (PixelFrame, MarkdownRenderer, etc.)
β β βββ styles/ # CSS design tokens & Tailwind imports
β β βββ utils/ # API client wrapper (`apiFetch`)
β βββ vercel.json # Vercel SPA proxy & rewrite configuration
βββ docker-compose.yml # Local multi-container development environment
π Running Locallyβ
Option A: Docker Compose (Recommended)β
docker-compose up --build
- Frontend: http://localhost:8080
- Backend API Docs: http://localhost:8000/docs
- PostgreSQL: localhost:5432
Option B: Manual Startupβ
-
Backend:
cd backendpython -m venv venv.\venv\Scripts\Activate.ps1 # Windowspip install -r requirements.txtalembic upgrade headpython -m uvicorn app.main:app --port 8000 --reload -
Frontend:
cd frontendnpm installnpm run dev