Chuyển tới nội dung chính

Application Overview: LinguFlow

LinguFlow is a modern, keyboard-driven language learning platform designed for high-efficiency study and certification exam simulation.


🌟 Key Features​

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.

🏗️ Technology Stack​

LayerTechnologies
FrontendVue 3 (Composition API <script setup>), TypeScript, Vite, TailwindCSS, Pinia, Marked, DOMPurify
BackendPython 3.12, FastAPI, Uvicorn, Pydantic Settings v2, Python-Jose (JWT), Passlib (bcrypt)
DatabasePostgreSQL 16, AsyncPG, SQLAlchemy 2.0 (Asyncio), Alembic Migrations
StorageCloudflare 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​

docker-compose up --build

Option B: Manual Startup​

  1. Backend:

    cd backend
    python -m venv venv
    .\venv\Scripts\Activate.ps1 # Windows
    pip install -r requirements.txt
    alembic upgrade head
    python -m uvicorn app.main:app --port 8000 --reload
  2. Frontend:

    cd frontend
    npm install
    npm run dev