LinguaFlow – AI-Powered Bilingual Deep Reading Platform

1. Product Overview

• One-line description: User enters an English webpage URL (or pastes text manually); the system extracts the main content and provides hover/click bilingual translation; supports silent vocabulary saving, in-reading highlight review, vocabulary deck card review, and export.
• Core scenario: Standalone web app, multi-device; English shown by default, Chinese shown on hover/click.
• MVP scope (aligned with full requirements)
  1. URL-based content extraction only; on failure, provide manual text paste entry
  2. Paragraph-level bilingual translation; Chinese shown on hover/click
  3. One-tap silent save (word / phrase / full sentence); AI picks a single contextual definition
  4. “My Library” auto-archives extracted articles
  5. In-reading highlight of saved vocabulary
  6. Vocabulary page: card view (flip to see definition), mastery-level tagging
  7. Export: Anki / PDF / Excel (fields include example sentence, part of speech, synonyms, article source link)
  8. Login: Email / GitHub / WeChat (sync across devices)
  9. Subscription / quota: platform translation service, user pays
  10. Bilingual UI (Chinese & English)

---

2. Tech Stack

---

3. Project Structure

src/
├── app/
│   ├── (auth)/                 # Login / signup (multi-device sync)
│   ├── (dashboard)/
│   │   ├── library/            # My Library (article list)
│   │   ├── vocabulary/         # Vocabulary (card view)
│   │   └── reader/[id]/        # Interactive reader
│   ├── api/
│   │   ├── extract/            # URL/text extraction and translation
│   │   ├── translate/          # Paragraph translation (retry, per-paragraph)
│   │   ├── words/              # Vocabulary CRUD / export / highlight
│   │   ├── articles/           # Article list and detail
│   │   └── billing/           # Subscription / quota
│   └── layout.tsx              # Global layout (language toggle)
├── components/
│   ├── reader/                 # Reader components
│   ├── vocab/                  # Vocabulary card components
│   ├── library/                # Library card components
│   └── ui/                     # Shared UI
├── lib/
│   ├── ai.ts                   # AI prompts and client wrapper
│   ├── extractor.ts            # Content extraction and cleaning
│   ├── scheduler.ts            # Spaced repetition scheduling
│   ├── i18n.ts                 # Bilingual strings
│   └── billing.ts              # Quota / subscription logic
├── prisma/
│   └── schema.prisma           # Data model
└── types/
    ├── api.ts                  # API type definitions
    └── domain.ts               # Domain model types

---

4. Data Model

// prisma/schema.prisma
enum MasteryLevel {
  FORGOTTEN
  FUZZY
  KNOWN
  MASTERED
}

enum AuthProvider {
  EMAIL
  GITHUB
  WECHAT
}

model User {
  id            String     @id @default(cuid())
  email         String     @unique
  name          String?
  image         String?
  provider      AuthProvider
  credits       Int        @default(0)  // remaining character quota
  isSubscribed  Boolean    @default(false)
  locale        String     @default("zh-CN")  // UI language
  createdAt     DateTime   @default(now())
  updatedAt     DateTime   @updatedAt

  articles      Article[]
  vocabularies  Vocabulary[]
  sessions      Session[]
}

model Article {
  id            String    @id @default(cuid())
  userId        String
  title         String
  sourceUrl     String?
  rawText       String    @db.Text
  content       Json      // Array<{en: string, zh: string, idx: number}>
  wordCount     Int
  createdAt     DateTime  @default(now())
  updatedAt     DateTime  @updatedAt

  user          User      @relation(fields: [userId], references: [id])
  vocabularies  Vocabulary[]
  @@index([userId, createdAt])
}

model Vocabulary {
  id              String        @id @default(cuid())
  userId          String
  sourceArticleId String?
  entryType       String        // "word" | "phrase" | "sentence"
  entryText       String        // word / phrase / sentence
  definition      String        // single contextual definition from AI
  partOfSpeech    String?       // part of speech (AI)
  synonyms        String?       // synonyms (AI, comma-separated)
  contextEn       String        @db.Text
  contextZh       String        @db.Text
  masteryLevel    MasteryLevel  @default(FUZZY)
  nextReviewAt    DateTime      @default(now())
  createdAt       DateTime      @default(now())
  updatedAt       DateTime      @updatedAt

  user            User          @relation(fields: [userId], references: [id])
  article         Article?      @relation(fields: [sourceArticleId], references: [id])
  @@index([userId, nextReviewAt])
  @@unique([userId, entryText, contextEn])  // dedupe same-word same-sentence
}

model Session {
  id        String   @id @default(cuid())
  userId    String
  token     String   @unique
  expiresAt DateTime
  user      User     @relation(fields: [userId], references: [id])
}

---

5. API Design

Unified response shape:

type ApiResponse<T> = { data: T; error?: { code: string; message: string } };

5.1 POST /api/extract

Purpose: Input URL or manual text; extract content and translate.

Auth: Required.

type ExtractRequest = {
  url?: string;         // mutually exclusive with manualText
  manualText?: string;  // fallback paste
};

type ExtractResponse = {
  articleId: string;
  title: string;
  paragraphs: Array<{ idx: number; en: string; zh: string }>;
  wordCount: number;
};

Logic

1. Validate: at least one of url or manualText.
2. Fetch or use text → clean content → split into paragraphs.
3. Compute wordCount, deduct credits (or skip if subscribed).
4. Call AI to translate paragraphs → zh.
5. Save Article, return articleId.

Error codes

• INVALID_INPUT: both url and manualText empty
• FETCH_FAILED: URL unreachable or blocked
• INSUFFICIENT_CREDITS: not enough credits
• AI_TIMEOUT: AI timeout
• AI_ERROR: AI failure

5.2 POST /api/translate

Purpose: Single-paragraph translation (retry or deferred).

type TranslateRequest = { text: string };
type TranslateResponse = { zh: string };

Error codes: AI_TIMEOUT, AI_ERROR, INVALID_INPUT

5.3 POST /api/words/collect

Purpose: Silent save on click (word / phrase / sentence).

type CollectRequest = {
  entryType: "word" | "phrase" | "sentence";
  entryText: string;
  contextEn: string;
  contextZh: string;
  articleId?: string;
};

type CollectResponse = {
  vocabId: string;
  masteryLevel: "FORGOTTEN" | "FUZZY" | "KNOWN" | "MASTERED";
};

Logic

1. Dedupe (same sentence + same entry = no duplicate).
2. AI generates single definition + part of speech + synonyms from context.
3. Save Vocabulary and return.

Error codes: DUPLICATE_ENTRY, AI_ERROR, INVALID_INPUT

5.4 GET /api/words/highlight

Purpose: List of vocabulary to highlight (not yet mastered).

type HighlightResponse = { entries: string[] };  // entryText list

Error codes: UNAUTHORIZED

5.5 POST /api/words/mastery

Purpose: Set mastery level and update next review time.

type MasteryRequest = {
  vocabId: string;
  masteryLevel: "FORGOTTEN" | "FUZZY" | "KNOWN" | "MASTERED";
};
type MasteryResponse = { nextReviewAt: string };

Error codes: NOT_FOUND, INVALID_INPUT

5.6 GET /api/words/export

Purpose: Export vocabulary.

type ExportRequest = { format: "anki" | "pdf" | "excel" };
type ExportResponse = { downloadUrl: string };

Error codes: INVALID_INPUT, EXPORT_FAILED

5.7 GET /api/articles

Purpose: My Library list.

type ArticlesResponse = {
  list: Array<{ id: string; title: string; sourceUrl?: string; createdAt: string }>;
};

5.8 GET /api/articles/:id

Purpose: Article detail.

type ArticleDetailResponse = {
  id: string;
  title: string;
  paragraphs: Array<{ idx: number; en: string; zh: string }>;
};

5.9 POST /api/billing/subscribe

Purpose: Create subscription or purchase credits.

type BillingRequest = { planId: string };
type BillingResponse = { checkoutUrl: string };

---

6. Pages and Components

6.1 Login /login

Components and props

• LoginForm
  • props: onSubmit(provider: "EMAIL" | "GITHUB" | "WECHAT")
  • state: loading: boolean, error: string | null

Interaction matrix

---

6.2 Library /library

Components

• ArticleCard: props { id, title, sourceUrl, createdAt }
• LibraryEmpty: empty state
• LibrarySkeleton: loading skeleton

State

• loading, error, articles[]

Interaction matrix

---

6.3 Reader /reader/[id]

Components and props

• ReaderHeader
  • props: { title, progress, onExport }
• ParagraphItem
  • props: { idx, en, zh, isActive, onHover }
  • state: showZh
• WordWrapper
  • props: { entryText, contextEn, contextZh, onCollect }
• FloatingDict
  • props: { entryText, definition, partOfSpeech, synonyms }

Page state

• activeParagraphIndex, isTranslating, highlightWords[], loading

Interaction matrix

Loading and empty

• loading: skeleton
• Empty content: message “Could not extract content; try pasting manually”

---

6.4 Vocabulary /vocabulary

Components

• Flashcard
  • props: { entryText, definition, contextEn, contextZh, partOfSpeech, synonyms }
  • state: flipped
• MasterySelector
  • props: { value, onChange }
• VocabEmpty / VocabSkeleton

Interaction matrix

---

7. Core User Flows

7.1 Happy path: read and save

1. User enters URL on home → POST /api/extract
2. Server parses content, translates paragraphs, saves article → returns articleId
3. Reader loads article and highlight list
4. Click on word triggers silent save → word is highlighted immediately, no modal
5. In vocabulary page: flip cards, set mastery level

7.2 Error paths and edge handling

• URL fetch fails: Prompt to use manual paste
• Insufficient credits: Open subscription / purchase modal
• AI timeout: Allow retry for single-paragraph translation
• Unauthorized: Redirect to login when accessing protected pages
• Duplicate save: Show “Already saved”, do not create new entry

7.3 Spaced repetition (pseudo-code)

// Stage days: 1, 2, 4, 7, 15
const stages = [1, 2, 4, 7, 15];

function nextReviewDate(currentLevel: MasteryLevel, now: Date): Date {
  if (currentLevel === "FORGOTTEN") return addDays(now, stages[0]);
  if (currentLevel === "FUZZY") return addDays(now, stages[1]);
  if (currentLevel === "KNOWN") return addDays(now, stages[2]);
  if (currentLevel === "MASTERED") return addDays(now, stages[4]);
  return addDays(now, stages[0]);
}

---

8. Environment Variables and Config