full size

.gitignore

@@ -0,0 +1,24 @@
+# Python
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.env
+*.egg-info/
+dist/
+.pytest_cache/
+
+# HuggingFace cache (too large for GitHub)
+~/.cache/huggingface/
+
+# Node
+node_modules/
+.env
+.env.local
+frontend/dist/
+
+# Editors
+.DS_Store
+.vscode/
+.idea/

Dockerfile

@@ -0,0 +1,31 @@
+# Dockerfile
+FROM python:3.10-slim
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+# Create a non-root user (Mandatory for Hugging Face Spaces)
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+# Install dependencies first (leverage Docker layer caching)
+COPY --chown=user requirements.txt .
+RUN pip install --user -r requirements.txt
+
+# Download the spaCy English model
+RUN python -m spacy download en_core_web_sm
+
+# Copy the rest of the application code
+COPY --chown=user . .
+
+# Expose the standard Hugging Face port
+EXPOSE 7860
+
+# Run the FastAPI application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,88 @@
+---
+title: WriteRight NLP Backend
+sdk: docker
+app_port: 7860
+---
+
+
+# WriteRight NLP API 🚀
+
+WriteRight is a production-grade NLP auto-correction and text refinement backend. It utilizes a multi-stage pipeline combining algorithmic rules with state-of-the-art Transformer models to provide instant spelling, grammar, and stylistic corrections.
+
+## 🧠 Architecture & Models
+
+The backend utilizes a decoupled architecture to ensure high precision:
+
+1. **Tokenization & NER:** `spaCy (en_core_web_sm)`
+2. **Spell Correction:** `SymSpell` (O(1) lookup, edit distance 1-2)
+3. **Homophone Resolution:** Context-aware POS heuristics
+4. **Grammar Correction:** `vennify/t5-base-grammar-correction` (T5 Encoder-Decoder)
+5. **Stylistic Refinement:** `eugenesiow/bart-paraphrase` (BART Sequence-to-Sequence)
+
+By separating **Grammar Correction** (T5) from **Stylistic Refinement** (BART), the system prevents prompt-leakage and maintains semantic integrity during paraphrasing.
+
+## 🔌 API Endpoints
+
+The API is built with **FastAPI** and is fully documented. Once running, visit `/docs` for the interactive Swagger UI.
+
+### 1. Correct Text (`POST /api/correct`)
+Executes the primary multi-stage correction pipeline.
+
+**Request:**
+\`\`\`json
+{
+  "text": "Thier going to the store to much.",
+  "run_spell": true,
+  "run_grammar": true,
+  "run_homophones": true
+}
+\`\`\`
+
+**Response:**
+\`\`\`json
+{
+  "original": "Thier going to the store to much.",
+  "corrected": "They're going to the store too much.",
+  "spell_fixed": 0,
+  "grammar_fixed": 1,
+  "homophone_fixed": 2,
+  "confidence": 0.89,
+  "diffs": [...],
+  "processing_ms": 345.2
+}
+\`\`\`
+
+### 2. Refine Text (`POST /api/refine`)
+Paraphrases and refines text for flow and style using the BART model.
+
+**Request:**
+\`\`\`json
+{
+  "text": "They're going to the store too much.",
+  "style": "professional"
+}
+\`\`\`
+
+## 🛠️ Local Setup & Development
+
+**Prerequisites:** Python 3.9+
+
+1. **Install dependencies:**
+   \`\`\`bash
+   pip install -r requirements.txt
+   python -m spacy download en_core_web_sm
+   \`\`\`
+
+2. **Run the server:**
+   \`\`\`bash
+   uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+   \`\`\`
+
+## ☁️ Hugging Face Deployment
+
+This repository is configured for automatic deployment on Hugging Face Spaces via Docker. 
+
+* **Port Mapping:** The Dockerfile routes Uvicorn to `7860` as required by HF Spaces.
+* **Cold Starts:** Upon the very first container initialization, the system will download the T5 and BART model weights (~1.5GB) from the Hugging Face Hub. Initial boot may take 2-3 minutes. Subsequent requests will be processed in-memory.
+
+---

backend/README.md

@@ -0,0 +1,55 @@
+2. Backend `README.md`
+Place this in your `backend/` directory (or the root of your Hugging Face Space).
+
+```markdown
+# WriteRight NLP API 🧠⚙️
+
+The core backend for **WriteRight**. This API processes text through a multi-stage Natural Language Processing pipeline to provide algorithmic spell checking, context-aware homophone resolution, structural grammar correction, and stylistic paraphrasing.
+
+## 🏗️ Architecture & Models
+
+The backend utilizes a decoupled architecture to ensure high precision and prevent prompt-leakage:
+
+1. **Pre-processing & Tokenization:** `spaCy` (`en_core_web_sm`)
+2. **Algorithmic Spell Correction:** `SymSpell` (O(1) dictionary lookup, edit distance 1-2)
+3. **Homophone Resolution:** Context-aware regex heuristics.
+4. **Grammar Correction:** `vennify/t5-base-grammar-correction` (Encoder-Decoder architecture fine-tuned specifically for grammar).
+5. **Stylistic Refinement:** `eugenesiow/bart-paraphrase` (BART Sequence-to-Sequence model for native text rewrites).
+
+## 🔌 Core API Endpoints
+
+The API is built with **FastAPI**. Once the server is running, visit `/docs` for the interactive OpenAPI/Swagger UI.
+
+* **`GET /api/health`**: System liveness and model loading status.
+* **`GET /api/stats`**: Aggregated usage metrics (words processed, average fixes).
+* **`POST /api/correct`**: Executes the primary multi-stage correction pipeline. Returns diffs, confidence scores, and fixed text.
+* **`POST /api/refine`**: Paraphrases and refines text for flow and style using the BART model.
+
+## 🛠️ Local Setup
+
+### Prerequisites
+* Python 3.9+
+
+### Setup Instructions
+
+1. **Install Python dependencies:**
+   ```bash
+   pip install -r requirements.txt
+Download the spaCy Language Model:
+
+Bash
+python -m spacy download en_core_web_sm
+Run the FastAPI server:
+
+Bash
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+The API will be available at http://localhost:8000.
+
+☁️ Hugging Face Spaces Deployment
+This repository is optimized for deployment via Docker on Hugging Face Spaces.
+
+Port Mapping: The Dockerfile automatically routes Uvicorn to port 7860, which is required by Hugging Face Spaces.
+
+Cold Starts: Upon the very first container initialization, the system will download the T5 and BART model weights (~1.5GB total) from the Hugging Face Hub. This initial boot may take 2-3 minutes. All subsequent requests are processed in-memory.
+
+Security: Runs as a non-root user (UID 1000) in compliance with HF Spaces security policies.

backend/app/__init__.py

@@ -0,0 +1 @@
+# app package

backend/app/api/routes.py

@@ -0,0 +1,108 @@
+"""
+app/api/routes.py
+─────────────────
+All REST endpoints for the WriteRight API.
+"""
+
+from __future__ import annotations
+from fastapi import APIRouter, Request, HTTPException
+from pydantic import BaseModel, Field, field_validator
+from loguru import logger
+import time
+
+from app.config import get_settings
+
+router = APIRouter()
+settings = get_settings()
+
+# ── Request / Response schemas ────────────────────────────────────────────────
+
+class CorrectionRequest(BaseModel):
+    text: str = Field(..., min_length=1, max_length=4096)
+    run_spell: bool = Field(True)
+    run_grammar: bool = Field(True)
+    run_homophones: bool = Field(True)
+
+    @field_validator("text")
+    @classmethod
+    def strip_and_validate(cls, v: str) -> str:
+        v = v.strip()
+        if not v: raise ValueError("text must not be blank")
+        return v
+
+class DiffEntry(BaseModel):
+    original: str
+    corrected: str
+    type: str
+    position: int
+
+class CorrectionResponse(BaseModel):
+    original: str
+    corrected: str
+    spell_fixed: int
+    grammar_fixed: int
+    homophone_fixed: int
+    confidence: float
+    diffs: list[DiffEntry]
+    processing_ms: float
+
+class RefineRequest(BaseModel):
+    text: str = Field(..., min_length=1, max_length=4096)
+    style: str = Field("professional")
+
+class RefineResponse(BaseModel):
+    original: str
+    refined: str
+    improvements: list[str]
+    processing_ms: float
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+@router.post("/correct", response_model=CorrectionResponse, tags=["NLP"])
+async def correct_text(body: CorrectionRequest, request: Request):
+    proc = request.app.state.processor
+    t0 = time.perf_counter()
+
+    try:
+        result = await proc.correct(
+            text=body.text,
+            run_spell=body.run_spell,
+            run_grammar=body.run_grammar,
+            run_homophones=body.run_homophones,
+        )
+    except Exception as e:
+        logger.error(f"/correct error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+
+    return CorrectionResponse(
+        original=body.text,
+        corrected=result["corrected"],
+        spell_fixed=result["spell_fixed"],
+        grammar_fixed=result["grammar_fixed"],
+        homophone_fixed=result["homophone_fixed"],
+        confidence=result["confidence"],
+        diffs=[DiffEntry(**d) for d in result["diffs"]],
+        processing_ms=round(elapsed_ms, 1),
+    )
+
+@router.post("/refine", response_model=RefineResponse, tags=["NLP"])
+async def refine_text(body: RefineRequest, request: Request):
+    proc = request.app.state.processor
+    t0 = time.perf_counter()
+
+    try:
+        result = await proc.refine(text=body.text, style=body.style)
+    except Exception as e:
+        logger.error(f"/refine error: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+
+    return RefineResponse(
+        original=body.text,
+        refined=result["refined"],
+        improvements=result["improvements"],
+        processing_ms=round(elapsed_ms, 1),
+    )

backend/app/config.py

@@ -0,0 +1,60 @@
+"""
+app/config.py
+─────────────
+Centralised settings loaded from environment / .env file.
+"""
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from functools import lru_cache
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parent
+
+class Settings(BaseSettings):
+    # ── App ──────────────────────────────────────────────
+    app_name: str = "WriteRight NLP API"
+    app_version: str = "1.0.0"
+    debug: bool = False
+
+    # ── CORS ─────────────────────────────────────────────
+    allowed_origins: list[str] = [
+        "http://localhost:5173",
+        "https://writeright.vercel.app",
+        "https://shikanja-malik-writeright-api.hf.space",
+    ]
+
+    # ── Models ────────────────────────────────────────────
+    # Grammar Model (T5 fine-tuned)
+    model_name: str = "prithivida/grammar_error_correcter_v1"
+    model_prefix: str = "grammar: "
+    
+    # Refinement Model (BERT-based BART architecture for paraphrasing/rewriting)
+    refine_model_name: str = "eugenesiow/bart-paraphrase"
+    
+    max_input_length: int = 512
+    max_output_length: int = 512
+    model_device: str = "cpu"          # "cuda" if GPU available
+
+    # ── Spell checker ─────────────────────────────────────
+    spell_dict_path: str = str(BASE_DIR / "resources" / "dictionary.txt")
+    spell_max_edit_distance: int = 2
+    spell_prefix_length: int = 7
+
+    # ── Homophones ────────────────────────────────────────
+    homophone_path: str = str(BASE_DIR / "resources" / "homophones.json")
+
+    # ── Pipeline ─────────────────────────────────────────
+    spacy_model: str = "en_core_web_sm"
+    min_word_length_for_spell: int = 2
+    skip_spell_for_proper_nouns: bool = True
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    return Settings()

backend/app/main.py

@@ -0,0 +1,85 @@
+"""
+app/main.py
+───────────
+FastAPI application entry-point.
+Bootstraps the NLP pipeline on startup and exposes the REST API.
+"""
+
+from contextlib import asynccontextmanager
+from loguru import logger
+import sys
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+
+from app.config import get_settings
+from app.api.routes import router
+from app.pipeline.processor import NLPProcessor
+
+# ── Logging ──────────────────────────────────────────────────────────────────
+logger.remove()
+logger.add(
+    sys.stderr,
+    format="<green>{time:HH:mm:ss}</green> | <level>{level: <8}</level> | {message}",
+    level="DEBUG",
+    colorize=True,
+)
+
+# ── Lifespan: startup / shutdown ─────────────────────────────────────────────
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    settings = get_settings()
+    logger.info(f"Starting {settings.app_name} v{settings.app_version}")
+
+    # Initialise the pipeline (loads spaCy + SymSpell + T5 + BART)
+    processor = NLPProcessor(settings)
+    await processor.initialise()
+    app.state.processor = processor
+
+    logger.info("Pipeline ready — API is live.")
+    yield
+
+    # Cleanup
+    logger.info("Shutting down — releasing model resources.")
+    del app.state.processor
+
+# ── App ───────────────────────────────────────────────────────────────────────
+settings = get_settings()
+
+app = FastAPI(
+    title=settings.app_name,
+    version=settings.app_version,
+    description=(
+        "NLP-based auto-corrector & paraphraser: spell correction via SymSpell, "
+        "grammar correction via T5, and style refinement via BART."
+    ),
+    lifespan=lifespan,
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+# ── CORS ──────────────────────────────────────────────────────────────────────
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.allowed_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ── Routes ────────────────────────────────────────────────────────────────────
+app.include_router(router, prefix="/api")
+
+# ── Global exception handler ─────────────────────────────────────────────────
+@app.exception_handler(Exception)
+async def global_exception_handler(request, exc):
+    logger.error(f"Unhandled exception: {exc}")
+    return JSONResponse(
+        status_code=500,
+        content={"detail": "Internal server error. Check logs for details."},
+    )
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("app.main:app", host="0.0.0.0", port=8000, reload=True)

backend/app/models/model_loader.py

@@ -0,0 +1,61 @@
+"""
+app/models/model_loader.py
+───────────────────────────
+Loads and caches:
+  • spaCy en_core_web_sm  — for tokenisation, POS tagging, NER
+  • HuggingFace T5        — for grammar correction
+  • HuggingFace BART      — for stylistic text refinement (paraphrasing)
+"""
+
+from __future__ import annotations
+from loguru import logger
+from app.config import Settings
+
+class ModelLoader:
+    def __init__(self, settings: Settings):
+        self._settings = settings
+
+    def load(self) -> tuple:
+        """
+        Returns (nlp, tokenizer_t5, model_t5, tokenizer_bart, model_bart).
+        """
+        nlp = self._load_spacy()
+        t5_tok, t5_mod = self._load_hf_model(self._settings.model_name, "Grammar (T5)")
+        bart_tok, bart_mod = self._load_hf_model(self._settings.refine_model_name, "Refine (BART)")
+        return nlp, t5_tok, t5_mod, bart_tok, bart_mod
+
+    def _load_spacy(self):
+        try:
+            import spacy
+            logger.info(f"Loading spaCy model: {self._settings.spacy_model}")
+            nlp = spacy.load(
+                self._settings.spacy_model,
+                disable=["ner"] if self._settings.skip_spell_for_proper_nouns else [],
+            )
+            return nlp
+        except Exception as e:
+            logger.error(f"spaCy load error: {e}")
+            return None
+
+    def _load_hf_model(self, model_name: str, label: str) -> tuple:
+        try:
+            from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
+            device = self._settings.model_device
+
+            logger.info(f"Loading {label} model: {model_name} on {device}")
+            tokenizer = AutoTokenizer.from_pretrained(model_name)
+            model = AutoModelForSeq2SeqLM.from_pretrained(model_name)
+
+            if device == "cuda":
+                try:
+                    model = model.to("cuda")
+                except Exception:
+                    logger.warning("CUDA unavailable, using CPU.")
+
+            model.eval()
+            logger.info(f"{label} model loaded successfully.")
+            return tokenizer, model
+
+        except Exception as e:
+            logger.error(f"{label} load error: {e}")
+            return None, None

backend/app/pipeline/grammar_corrector.py

@@ -0,0 +1,110 @@
+"""
+app/pipeline/grammar_corrector.py
+───────────────────────────────────
+Handles two independent tasks:
+1. Grammar Correction (T5)
+2. Text Refinement & Style Paraphrasing (BART)
+"""
+
+from __future__ import annotations
+import re
+from loguru import logger
+from app.config import Settings
+from app.utils.text_utils import count_word_diffs
+
+class GrammarCorrector:
+    def __init__(self, settings: Settings, tokenizer_t5, model_t5, tokenizer_bart, model_bart):
+        self._settings = settings
+        
+        # Grammar dependencies
+        self._tokenizer = tokenizer_t5
+        self._model = model_t5
+        
+        # Refinement dependencies
+        self._refine_tokenizer = tokenizer_bart
+        self._refine_model = model_bart
+
+    # ── Grammar correction ────────────────────────────────────────────────────
+
+    def correct(self, sentence: str) -> dict[str, object]:
+        if not self._tokenizer or not self._model:
+            return {"corrected": sentence, "fixes": 0}
+
+        sentence = sentence.strip()
+        if not sentence:
+            return {"corrected": sentence, "fixes": 0}
+
+        try:
+            prompt = self._settings.model_prefix + sentence
+            inputs = self._tokenizer.encode(
+                prompt, return_tensors="pt", max_length=self._settings.max_input_length, truncation=True
+            )
+            outputs = self._model.generate(
+                inputs, max_length=self._settings.max_output_length, num_beams=4, early_stopping=True
+            )
+            corrected = self._tokenizer.decode(outputs[0], skip_special_tokens=True)
+            fixes = count_word_diffs(sentence, corrected)
+            return {"corrected": corrected, "fixes": fixes}
+        except Exception as e:
+            logger.error(f"T5 grammar correction error: {e}")
+            return {"corrected": sentence, "fixes": 0}
+
+    # ── Refinement (CRITICAL BUG FIX) ─────────────────────────────────────────
+
+    def refine(self, text: str, style: str = "professional") -> dict[str, object]:
+        """
+        Uses the BART seq2seq model to paraphrase.
+        By removing conversational prompts (which leaked into output) and using a 
+        dedicated paraphrasing model, we return only clean, refined text.
+        """
+        if not self._refine_tokenizer or not self._refine_model:
+            return {"refined": text, "improvements": ["Refinement model not loaded."]}
+
+        try:
+            # We no longer prepend instructional prompts that confuse the model.
+            # BART paraphrase models expect raw text input.
+            inputs = self._refine_tokenizer.encode(
+                text, return_tensors="pt", max_length=self._settings.max_input_length, truncation=True
+            )
+            
+            # Adjusted generation params for distinct phrasing
+            outputs = self._refine_model.generate(
+                inputs,
+                max_length=self._settings.max_output_length,
+                num_beams=5,
+                early_stopping=True,
+                no_repeat_ngram_size=3,
+                temperature=0.7 # Slight variance for better natural phrasing
+            )
+            refined = self._refine_tokenizer.decode(outputs[0], skip_special_tokens=True)
+
+            improvements = self._detect_improvements(text, refined)
+            return {"refined": refined, "improvements": improvements}
+        except Exception as e:
+            logger.error(f"BART refinement error: {e}")
+            return {"refined": text, "improvements": [f"Refinement error: {e}"]}
+
+    @staticmethod
+    def _detect_improvements(original: str, refined: str) -> list[str]:
+        improvements: list[str] = []
+        orig_words = original.split()
+        ref_words = refined.split()
+
+        if len(ref_words) < len(orig_words) * 0.9:
+            improvements.append("Condensed verbose phrasing for clarity.")
+        if len(ref_words) > len(orig_words) * 1.1:
+            improvements.append("Expanded phrases for improved readability.")
+
+        orig_sents = re.split(r"[.!?]+", original)
+        ref_sents = re.split(r"[.!?]+", refined)
+        if len(ref_sents) != len(orig_sents):
+            improvements.append("Restructured sentences for better flow.")
+
+        passive_re = re.compile(r"\bwas\s+\w+ed\b|\bwere\s+\w+ed\b", re.I)
+        if passive_re.search(original) and not passive_re.search(refined):
+            improvements.append("Converted passive constructions to active voice.")
+
+        if not improvements:
+            improvements.append("Improved vocabulary and sentence cohesion.")
+
+        return improvements[:3]

backend/app/pipeline/homophone_resolver.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+import re
+from loguru import logger
+from app.config import Settings
+
+_RULES = [
+    (re.compile(r"\bthier\b", re.I), "thier", "their"),
+    (re.compile(r"\btheir\s+is\b", re.I), "their is", "there is"),
+    (re.compile(r"\byour\s+(?:going|coming|doing|being)\b", re.I), "your", "you're"),
+    (re.compile(r"\byoure\b", re.I), "youre", "you're"),
+    (re.compile(r"\bits\s+(?:a|an|the|not|been|going)\b", re.I), "its", "it's"),
+    (re.compile(r"\b(?:more|less|better|worse)\s+then\b", re.I), "then", "than"),
+    (re.compile(r"\bto\s+(?:much|many|late|soon)\b", re.I), "to much", "too much"),
+    (re.compile(r"\bweather\s+or\s+not\b", re.I), "weather", "whether"),
+]
+
+class HomophoneResolver:
+    def __init__(self, settings: Settings):
+        self._settings = settings
+
+    def load(self) -> bool:
+        return True # Relying on heuristic rules for speed
+
+    def resolve(self, text: str) -> dict[str, object]:
+        fixes = 0
+        result = text
+        for pattern, wrong, correct in _RULES:
+            if pattern.search(result):
+                old = result
+                result = self._replace_preserving_case(result, wrong, correct)
+                if result != old: fixes += 1
+        return {"corrected": result, "fixes": fixes}
+
+    @staticmethod
+    def _replace_preserving_case(text: str, wrong: str, correct: str) -> str:
+        def replacer(m: re.Match) -> str:
+            original = m.group(0)
+            if original.isupper(): return correct.upper()
+            if original[0].isupper(): return correct.capitalize()
+            return correct
+        return re.sub(re.escape(wrong), replacer, text, flags=re.IGNORECASE)

backend/app/pipeline/processor.py

@@ -0,0 +1,121 @@
+"""
+app/pipeline/processor.py
+──────────────────────────
+Orchestrates the full NLP correction pipeline:
+  Pre-process → Spell → Homophones → Grammar → Score → Diff
+"""
+
+from __future__ import annotations
+import asyncio
+from loguru import logger
+
+from app.config import Settings
+from app.pipeline.spell_checker import SpellChecker
+from app.pipeline.homophone_resolver import HomophoneResolver
+from app.pipeline.grammar_corrector import GrammarCorrector
+from app.pipeline.scorer import Scorer
+from app.models.model_loader import ModelLoader
+from app.utils.text_utils import split_into_sentences, normalise_whitespace, build_word_diffs
+
+class NLPProcessor:
+    def __init__(self, settings: Settings):
+        self._settings = settings
+        self.spacy_ready: bool = False
+        self.symspell_ready: bool = False
+        self.t5_ready: bool = False
+
+        self._spell_checker: SpellChecker | None = None
+        self._homophone_resolver: HomophoneResolver | None = None
+        self._grammar_corrector: GrammarCorrector | None = None
+        self._scorer: Scorer | None = None
+        self._model_loader: ModelLoader | None = None
+
+    async def initialise(self) -> None:
+        logger.info("Initialising NLP pipeline…")
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, self._load_all)
+        logger.info(f"Pipeline ready | spaCy={self.spacy_ready} SymSpell={self.symspell_ready} T5={self.t5_ready}")
+
+    def _load_all(self) -> None:
+        s = self._settings
+        self._model_loader = ModelLoader(s)
+        
+        # Unpack both models
+        nlp, t5_tok, t5_mod, bart_tok, bart_mod = self._model_loader.load()
+
+        if nlp: self.spacy_ready = True
+
+        self._spell_checker = SpellChecker(s)
+        if self._spell_checker.load(): self.symspell_ready = True
+
+        self._homophone_resolver = HomophoneResolver(s)
+        self._homophone_resolver.load()
+
+        # Inject both models into the corrector
+        self._grammar_corrector = GrammarCorrector(s, t5_tok, t5_mod, bart_tok, bart_mod)
+        if t5_tok and t5_mod: self.t5_ready = True
+
+        self._scorer = Scorer(nlp)
+
+    async def correct(self, text: str, run_spell: bool = True, run_grammar: bool = True, run_homophones: bool = True) -> dict:
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, self._correct_sync, text, run_spell, run_grammar, run_homophones)
+
+    def _correct_sync(self, text: str, run_spell: bool, run_grammar: bool, run_homophones: bool) -> dict:
+        original = text
+        spell_fixed = grammar_fixed = homophone_fixed = 0
+        all_diffs: list[dict] = []
+
+        current = normalise_whitespace(text)
+
+        if run_spell and self._spell_checker and self.symspell_ready:
+            spell_result = self._spell_checker.correct(current)
+            if spell_result["corrected"] != current:
+                diffs = build_word_diffs(current, spell_result["corrected"], "spell")
+                all_diffs.extend(diffs)
+                spell_fixed = spell_result["fixes"]
+                current = spell_result["corrected"]
+
+        if run_homophones and self._homophone_resolver:
+            hom_result = self._homophone_resolver.resolve(current)
+            if hom_result["corrected"] != current:
+                diffs = build_word_diffs(current, hom_result["corrected"], "homophone")
+                all_diffs.extend(diffs)
+                homophone_fixed = hom_result["fixes"]
+                current = hom_result["corrected"]
+
+        if run_grammar and self._grammar_corrector:
+            sentences = split_into_sentences(current)
+            corrected_sentences = []
+            for sent in sentences:
+                gram_result = self._grammar_corrector.correct(sent)
+                corrected_sentences.append(gram_result["corrected"])
+                grammar_fixed += gram_result["fixes"]
+
+            grammar_text = " ".join(corrected_sentences)
+            if grammar_text != current:
+                diffs = build_word_diffs(current, grammar_text, "grammar")
+                all_diffs.extend(diffs)
+                current = grammar_text
+
+        confidence = 1.0
+        if self._scorer:
+            confidence = self._scorer.score(original, current)
+
+        return {
+            "corrected": current,
+            "spell_fixed": spell_fixed,
+            "grammar_fixed": grammar_fixed,
+            "homophone_fixed": homophone_fixed,
+            "confidence": round(confidence, 3),
+            "diffs": all_diffs,
+        }
+
+    async def refine(self, text: str, style: str = "professional") -> dict:
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, self._refine_sync, text, style)
+
+    def _refine_sync(self, text: str, style: str) -> dict:
+        if self._grammar_corrector:
+            return self._grammar_corrector.refine(text, style)
+        return {"refined": text, "improvements": ["Model not loaded; no refinement applied."]}

backend/app/pipeline/scorer.py

@@ -0,0 +1,97 @@
+"""
+app/pipeline/scorer.py
+───────────────────────
+Confidence scoring for the correction pipeline.
+
+Produces a value in [0, 1] reflecting how much the text changed and
+whether the changes seem linguistically reasonable.
+
+Heuristics used:
+  • Normalised edit distance between original and corrected
+  • Token overlap ratio (Jaccard)
+  • spaCy entity preservation check (named entities should survive)
+  • Penalty if corrected text is much longer / shorter than original
+"""
+
+from __future__ import annotations
+
+import math
+import re
+
+from loguru import logger
+
+
+class Scorer:
+    def __init__(self, nlp=None):
+        """
+        :param nlp: spaCy Language model (optional but improves scoring).
+        """
+        self._nlp = nlp
+
+    def score(self, original: str, corrected: str) -> float:
+        """Return a confidence score in [0.0, 1.0]."""
+        if not original or not corrected:
+            return 1.0
+
+        if original == corrected:
+            return 1.0
+
+        try:
+            sim   = self._token_similarity(original, corrected)
+            ratio = self._length_ratio(original, corrected)
+            ent   = self._entity_preservation(original, corrected)
+
+            # Weighted average
+            score = 0.5 * sim + 0.25 * ratio + 0.25 * ent
+            return max(0.0, min(1.0, score))
+        except Exception as e:
+            logger.warning(f"Scorer error: {e}")
+            return 0.85  # safe fallback
+
+    # ── Sub-metrics ────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _token_similarity(a: str, b: str) -> float:
+        """Jaccard similarity on word-token sets."""
+        ta = set(re.findall(r"\b\w+\b", a.lower()))
+        tb = set(re.findall(r"\b\w+\b", b.lower()))
+        if not ta and not tb:
+            return 1.0
+        intersection = len(ta & tb)
+        union = len(ta | tb)
+        return intersection / union if union else 1.0
+
+    @staticmethod
+    def _length_ratio(a: str, b: str) -> float:
+        """
+        Penalises large length differences.
+        Returns 1.0 when lengths match, decays toward 0 as ratio diverges.
+        """
+        la, lb = len(a.split()), len(b.split())
+        if la == 0:
+            return 1.0
+        ratio = min(la, lb) / max(la, lb)
+        # Apply mild sigmoid to soften extreme cases
+        return 1 / (1 + math.exp(-10 * (ratio - 0.5)))
+
+    def _entity_preservation(self, a: str, b: str) -> float:
+        """
+        Check that named entities in the original survive in the corrected text.
+        Falls back to 1.0 if spaCy is unavailable.
+        """
+        if not self._nlp:
+            return 1.0
+
+        try:
+            doc_a = self._nlp(a)
+            doc_b = self._nlp(b)
+            ents_a = {ent.text.lower() for ent in doc_a.ents}
+            ents_b = {ent.text.lower() for ent in doc_b.ents}
+
+            if not ents_a:
+                return 1.0
+
+            preserved = len(ents_a & ents_b)
+            return preserved / len(ents_a)
+        except Exception:
+            return 1.0

backend/app/pipeline/spell_checker.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+import re
+from pathlib import Path
+from loguru import logger
+from app.config import Settings
+
+try:
+    from symspellpy import SymSpell, Verbosity
+    SYMSPELL_AVAILABLE = True
+except ImportError:
+    SYMSPELL_AVAILABLE = False
+    logger.warning("symspellpy not installed.")
+
+_SKIP_PATTERNS = re.compile(r"^https?://|^www\.\d|^[A-Z]{2,}$|^[A-Z][a-z]+[A-Z]", re.VERBOSE)
+
+class SpellChecker:
+    def __init__(self, settings: Settings):
+        self._settings = settings
+        self._sym: SymSpell | None = None
+
+    def load(self) -> bool:
+        if not SYMSPELL_AVAILABLE: return False
+        self._sym = SymSpell(
+            max_dictionary_edit_distance=self._settings.spell_max_edit_distance,
+            prefix_length=self._settings.spell_prefix_length,
+        )
+        try:
+            import pkg_resources
+            freq_dict = pkg_resources.resource_filename("symspellpy", "frequency_dictionary_en_82_765.txt")
+            self._sym.load_dictionary(freq_dict, term_index=0, count_index=1)
+            return True
+        except Exception as e:
+            logger.error(f"Could not load dictionary: {e}")
+            return False
+
+    def correct(self, text: str) -> dict[str, object]:
+        if not self._sym: return {"corrected": text, "fixes": 0}
+        tokens = re.split(r"(\s+)", text)
+        fixes = 0
+        out_tokens = []
+        for token in tokens:
+            if re.match(r"^\s+$", token):
+                out_tokens.append(token)
+                continue
+            corrected_token = self._correct_token(token)
+            if corrected_token.lower() != token.lower(): fixes += 1
+            out_tokens.append(corrected_token)
+        return {"corrected": "".join(out_tokens), "fixes": fixes}
+
+    def _correct_token(self, token: str) -> str:
+        m = re.match(r"^([^a-zA-Z']*)([a-zA-Z']+)([^a-zA-Z']*)$", token)
+        if not m: return token
+        pre, word, post = m.group(1), m.group(2), m.group(3)
+        if len(word) <= self._settings.min_word_length_for_spell or _SKIP_PATTERNS.match(token):
+            return token
+        suggestions = self._sym.lookup(word.lower(), Verbosity.CLOSEST, max_edit_distance=self._settings.spell_max_edit_distance, include_unknown=True)
+        if not suggestions: return token
+        best = suggestions[0].term
+        if word.isupper(): best = best.upper()
+        elif word[0].isupper(): best = best.capitalize()
+        return pre + best + post

backend/app/resources/dictionary.txt

@@ -0,0 +1,895 @@
+the	23135851162
+be	13047913334
+to	12136980858
+of	11820836747
+and	10989497138
+a	10427512430
+in	8507281891
+that	7517730288
+have	6332185948
+it	5430541382
+for	4997722092
+not	4801285117
+on	4393142827
+with	4029515580
+he	3823871886
+as	3427985255
+you	3196816182
+do	3131510655
+at	2869637029
+this	2845892349
+but	2680153038
+his	2667609292
+by	2543163226
+from	2374401740
+they	2232267448
+we	2109019013
+say	2034311816
+her	1987261827
+she	1887671418
+or	1883558688
+an	1877617239
+will	1871894427
+my	1844518463
+one	1784649037
+all	1764372325
+would	1753396418
+there	1697748860
+their	1692028469
+what	1672397224
+so	1614701173
+up	1606261547
+out	1585019526
+if	1539994854
+about	1486618582
+who	1456791147
+get	1432069524
+which	1406168949
+go	1399748023
+me	1389376087
+when	1378090840
+make	1370462898
+can	1358527726
+like	1337416424
+time	1307368028
+no	1306069636
+just	1285200450
+him	1258736792
+know	1255891088
+take	1217432073
+people	1200748066
+into	1195302738
+year	1155716074
+your	1148824302
+good	1100481453
+some	1087131892
+could	1072940878
+them	1069048218
+see	1062551219
+other	1059528497
+than	1050780447
+then	1044044680
+now	1036888474
+look	1035090920
+only	1024898714
+come	1021688283
+its	1021009688
+over	1005887756
+think	993978026
+also	979960350
+back	973524093
+after	963920424
+use	957289006
+two	954393614
+how	949977754
+our	949463625
+work	928975027
+first	925920870
+well	920406394
+way	914476578
+even	911090614
+new	907988449
+want	907234302
+because	896476892
+any	887671451
+these	883173820
+give	869832637
+day	860024628
+most	844543003
+us	840124234
+great	823721764
+between	786614100
+need	783609951
+large	780695513
+often	778690396
+hand	776503568
+high	770406359
+place	764700677
+hold	762248718
+world	761118640
+found	751019296
+still	742064648
+learn	737700100
+plant	736609716
+cover	729513282
+food	726600130
+sun	724421042
+four	722019754
+thought	719717224
+let	718813948
+keep	718064716
+children	711264132
+feet	710006048
+side	706012284
+without	702624438
+boy	700607012
+once	699700064
+animal	698219120
+life	697721780
+enough	696026928
+took	694399756
+sometimes	693234860
+four	692567868
+always	691455888
+those	690866928
+both	688813748
+paper	685820464
+together	682924156
+got	681217700
+group	677802320
+often	674997004
+run	674344416
+important	673613156
+until	673163588
+children	671694308
+side	669965152
+feet	667614564
+car	665900220
+mile	662823440
+night	661444056
+walk	659888340
+white	658869392
+sea	656992164
+began	654853664
+grow	651904028
+took	649677476
+river	648718488
+four	646714148
+carry	645818732
+state	644703476
+once	641844164
+book	640803592
+hear	639854912
+stop	637718860
+without	636892820
+second	635671556
+later	633894900
+miss	633058484
+idea	629874540
+enough	628729848
+eat	628047748
+face	625890232
+watch	623762768
+far	622873316
+Indian	620952404
+really	619726348
+almost	617891252
+let	617185284
+above	616553032
+girl	616166684
+sometimes	615780032
+mountain	614668660
+cut	613836796
+young	613021752
+talk	611744940
+soon	610804936
+list	609928508
+song	609066436
+leave	608153748
+family	607362272
+body	606613452
+music	605788456
+color	604998232
+stand	604159636
+sun	603334504
+questions	602582212
+fish	601791140
+area	600994260
+mark	600258948
+dog	599554380
+horse	599083596
+birds	598548028
+problem	598131716
+complete	597605484
+room	597091200
+knew	596633136
+since	596222892
+ever	595769780
+piece	595346760
+told	594982420
+usually	594566356
+didn't	594106232
+friends	593691736
+easy	593246828
+heard	592828048
+order	592464296
+red	592064960
+door	591672108
+sure	591296616
+become	590927236
+top	590604420
+ship	590244476
+across	589899980
+today	589511692
+during	589159356
+short	588804860
+better	588444984
+best	588101696
+however	587748032
+low	587401632
+hours	587055892
+black	586706432
+products	586363764
+happened	586019740
+whole	585671868
+measure	585325120
+remember	584978560
+early	584632540
+waves	584289648
+reached	583945716
+listen	583602752
+wind	583258072
+rock	582907720
+space	582555248
+covered	582212892
+fast	581866844
+several	581517780
+hold	581175800
+himself	580826272
+toward	580475856
+five	580130312
+step	579774028
+morning	579425152
+passed	579071064
+vowel	578717452
+true	578366580
+hundred	578014996
+against	577662480
+pattern	577310128
+numeral	576956796
+table	576603896
+north	576252116
+slowly	575899252
+money	575547488
+map	575194152
+farm	574842136
+pulled	574489040
+draw	574136388
+voice	573785576
+seen	573429900
+cold	573073872
+cried	572717064
+plan	572360400
+notice	572005016
+south	571651600
+sing	571291780
+war	570935772
+ground	570579996
+fall	570224008
+king	569869408
+town	569512648
+I'll	569157764
+unit	568799064
+figure	568441940
+certain	568082564
+field	567723120
+travel	567361284
+wood	566999220
+fire	566637916
+upon	566279744
+done	565920200
+english	565562392
+road	565201428
+half	564842644
+ten	564484760
+fly	564126892
+gave	563768060
+box	563404256
+finally	563039940
+wait	562678600
+correct	562318528
+oh	561959312
+quickly	561600892
+person	561244988
+became	560885480
+shown	560527592
+minutes	560167728
+strong	559807348
+verb	559448128
+stars	559087948
+front	558729664
+feel	558373696
+fact	558014396
+inches	557657052
+street	557300988
+decided	556943060
+contain	556584664
+course	556225468
+surface	555867668
+produce	555509372
+building	555150732
+ocean	554791732
+class	554431916
+note	554073196
+nothing	553716480
+rest	553358852
+carefully	552999216
+scientists	552641584
+inside	552283916
+wheels	551926252
+stay	551566984
+green	551207460
+known	550850896
+island	550491624
+week	550132164
+less	549772408
+machine	549414804
+base	549055504
+ago	548696844
+stood	548337256
+plane	547977044
+system	547617852
+behind	547258744
+ran	546899200
+round	546541936
+boat	546179756
+game	545818712
+force	545459288
+brought	545098352
+understand	544739948
+warm	544380200
+common	544022632
+bring	543661584
+explain	543302420
+dry	542942852
+though	542581844
+language	542219920
+shape	541857988
+deep	541496644
+thousands	541136236
+yes	540775528
+clear	540413760
+equation	540052996
+yet	539692432
+government	539330772
+filled	538970244
+heat	538607908
+full	538246484
+hot	537886088
+check	537525936
+object	537163292
+am	536803048
+rule	536440272
+among	536077940
+noun	535717120
+power	535356968
+cannot	534994008
+able	534633980
+six	534271564
+size	533910308
+dark	533547024
+ball	533183972
+material	532820692
+special	532459644
+heavy	532095060
+fine	531733068
+pair	531372900
+circle	531009652
+include	530648488
+built	530287024
+can't	529925548
+matter	529562048
+square	529200388
+syllables	528838724
+perhaps	528477836
+bill	528116548
+felt	527753172
+suddenly	527391448
+test	527028532
+direction	526665760
+center	526301848
+farmers	525939996
+ready	525578148
+anything	525218304
+divided	524853376
+general	524489048
+energy	524125216
+subject	523762404
+europe	523400652
+moon	523037604
+region	522676888
+return	522315040
+believe	521952832
+dance	521589588
+members	521228292
+picked	520866016
+simple	520503728
+cells	520140996
+paint	519777624
+mind	519415140
+love	519051456
+cause	518688676
+rain	518325012
+exercise	517962492
+eggs	517600240
+train	517237636
+blue	516876888
+wish	516513900
+drop	516149264
+developed	515784516
+window	515419228
+difference	515055696
+distance	514690948
+heart	514327984
+sit	513961712
+sum	513597336
+summer	513234612
+wall	512868516
+forest	512503916
+probably	512138360
+legs	511773056
+sat	511407804
+main	511042460
+winter	510677616
+wide	510311248
+written	509945776
+length	509579840
+reason	509213680
+kept	508847220
+interest	508480492
+arms	508113400
+brother	507744596
+race	507377948
+present	507011180
+beautiful	506643336
+store	506276936
+job	505908980
+edge	505541908
+past	505175076
+sign	504807444
+record	504440428
+finished	504073400
+discovered	503706184
+wild	503339256
+happy	502972712
+beside	502605196
+gone	502237296
+sky	501869640
+glass	501500148
+million	501131780
+west	500764716
+lay	500397076
+weather	500028908
+root	499660800
+instruments	499293208
+meet	498925992
+third	498557980
+months	498190164
+paragraph	497822648
+raised	497455636
+represent	497088108
+soft	496720608
+whether	496352788
+clothes	495984316
+flowers	495615852
+shall	495247236
+teacher	494879996
+held	494512652
+describe	494143624
+drive	493775664
+cross	493407920
+speak	493041076
+solve	492672464
+appear	492303868
+metal	491935772
+son	491568360
+either	491200224
+ice	490831436
+sleep	490463480
+village	490095524
+factors	489726228
+result	489358376
+jumped	488990528
+snow	488621496
+ride	488252248
+care	487883220
+floor	487515472
+hill	487146824
+pushed	486778252
+baby	486409208
+buy	486040756
+century	485672492
+outside	485303832
+everything	484935188
+tall	484566892
+already	484198776
+instead	483829804
+phrase	483461176
+soil	483092848
+bed	482724572
+copy	482354744
+free	481985832
+hope	481617916
+spring	481248104
+case	480878852
+laughed	480510684
+nation	480142828
+quite	479772372
+type	479403892
+themselves	479034680
+temperature	478665640
+bright	478296560
+lead	477927832
+everyone	477558236
+method	477189444
+section	476821032
+lake	476451848
+iron	476082196
+within	475713360
+dictionary	475344392
+hair	474975104
+age	474605764
+amount	474235432
+scale	473866116
+pounds	473497096
+although	473127800
+per	472758432
+broken	472389300
+moment	472019308
+tiny	471649924
+possible	471280244
+gold	470910612
+milk	470541360
+quiet	470171948
+natural	469801408
+lot	469432608
+stone	469063096
+act	468693396
+build	468323128
+middle	467954420
+speed	467584564
+count	467215072
+consonant	466845616
+someone	466475952
+sail	466107088
+rolled	465737464
+bear	465367228
+wonder	464997516
+smiled	464628244
+angle	464258324
+fraction	463888872
+Africa	463519868
+killed	463149948
+melody	462779168
+bottom	462409964
+trip	462040292
+hole	461671208
+poor	461300716
+let's	460930092
+fight	460560364
+surprise	460191492
+French	459820880
+died	459451392
+beat	459081604
+exactly	458712296
+remain	458342252
+dress	457972960
+iron	457601668
+couldn't	457231848
+fingers	456862172
+row	456492656
+least	456122380
+catch	455753132
+climbed	455383592
+wrote	455013208
+shouted	454643748
+continued	454273616
+itself	453903680
+else	453534260
+plains	453163872
+gas	452793528
+England	452424080
+burning	452053568
+design	451683624
+joined	451314640
+foot	450944824
+law	450575116
+ears	450204680
+grass	449833888
+you've	449463864
+grown	449094448
+valley	448723892
+cents	448354388
+key	447983408
+president	447612796
+brown	447241560
+trouble	446870992
+cool	446501360
+cloud	446130768
+lost	445760224
+sent	445390672
+symbols	445019456
+wear	444648864
+bad	444278960
+save	443908880
+experiment	443539180
+engine	443168968
+alone	442798532
+drawing	442428400
+east	442058972
+pay	441689728
+single	441319108
+touch	440948836
+information	440578736
+express	440209572
+mouth	439839408
+yard	439470116
+equal	439099752
+decimal	438728664
+yourself	438358360
+control	437988168
+practice	437617932
+report	437248120
+straight	436877656
+rise	436507184
+statement	436137448
+stick	435767216
+party	435396484
+seeds	435026988
+suppose	434656328
+woman	434286064
+coast	433915556
+bank	433544100
+period	433174420
+wire	432803184
+choose	432432680
+clean	432062528
+visit	431691284
+bit	431320996
+whose	430951008
+received	430579948
+garden	430208796
+please	429838672
+strange	429467512
+caught	429097724
+fell	428726576
+team	428356424
+God	427985192
+captain	427614060
+direct	427244240
+ring	426872872
+serve	426501616
+child	426131516
+desert	425760532
+increase	425389496
+history	425018456
+cost	424647628
+maybe	424277064
+business	423906212
+separate	423534992
+break	423164840
+uncle	422793864
+hunting	422423624
+flow	422053016
+lady	421681936
+students	421311076
+human	420940276
+art	420568952
+feeling	420198032
+supply	419828616
+corner	419457300
+electric	419085348
+insects	418714608
+crops	418343876
+tone	417972872
+hit	417601588
+sand	417231284
+doctor	416860296
+provide	416489124
+thus	416118936
+won't	415747944
+cook	415376548
+bones	415006040
+tail	414634484
+board	414263892
+modern	413893892
+compound	413523432
+mine	413151964
+wasn't	412780536
+fit	412410156
+addition	412038444
+belong	411667816
+safe	411295872
+soldiers	410924888
+guess	410553288
+silent	410182580
+trade	409811500
+rather	409440700
+compare	409069888
+crowd	408698048
+poem	408327368
+enjoy	407955688
+elements	407584560
+indicate	407213504
+except	406841800
+expect	406470912
+flat	406100000
+seven	405728488
+interesting	405357304
+sense	404985512
+string	404614260
+blow	404242680
+famous	403871996
+value	403501188
+wings	403130436
+movement	402759128
+pole	402387968
+exciting	402016852
+branches	401645984
+thick	401274296
+blood	400903824
+lie	400532840
+spot	400160352
+bell	399789892
+fun	399418224
+loud	399047888
+consider	398676416
+suggested	398305432
+thin	397934780
+position	397563940
+entered	397192676
+fruit	396821220
+tied	396450044
+rich	396078636
+dollars	395707812
+send	395336596
+sight	394965488
+chief	394594144
+Japanese	394223504
+stream	393852160
+planets	393480788
+rhythm	393110308
+eight	392738876
+science	392367880
+major	391996932
+observe	391626476
+tube	391254728
+necessary	390883884
+weight	390512976
+meat	390141884
+lifted	389770756
+process	389399780
+army	389029072
+hat	388658228
+property	388287052
+particular	387915720
+swim	387544248
+terms	387172936
+current	386801936
+park	386430704
+sell	386059576
+shoulder	385688448
+industry	385317176
+wash	384945612
+block	384574464
+spread	384203016
+cattle	383832208
+wife	383460632
+sharp	383089344
+company	382717680
+radio	382346380
+we'll	381975796
+action	381603976
+capital	381232508
+factories	380861432
+settled	380490368
+yellow	380119624
+isn't	379748000
+southern	379375720
+truck	379004428
+fair	378633048
+printed	378262296
+wouldn't	377889848
+ahead	377518720
+chance	377147408
+born	376776056
+level	376404856
+triangle	376034012
+molecules	375663200
+France	375292312
+repeated	374920612
+column	374549440
+western	374178948
+church	373808132
+sister	373437012
+oxygen	373065548
+plural	372693852
+various	372323512
+agreed	371952880
+opposite	371580688
+wrong	371210492
+chart	370839456
+prepared	370469348
+pretty	370097916
+solution	369726104
+fresh	369355832
+shop	368983776
+suffix	368612256
+especially	368242104
+shoes	367871052
+actually	367499800
+nose	367128332
+afraid	366756584
+dead	366386024
+sugar	366015500
+adjective	365644020
+fig	365273136
+office	364901824
+huge	364530552
+gun	364160236
+similar	363789520
+death	363418140
+score	363047164
+forward	362676124
+stretched	362305504
+experience	361933864
+rose	361562348
+allow	361191660
+fear	360820492
+workers	360449476
+Washington	360079584
+Greek	359708280
+women	359336900
+bought	358965544
+led	358594908
+march	358223364
+northern	357852648
+create	357481068
+British	357110100
+difficult	356738832
+match	356367268
+win	355996800
+doesn't	355625856
+steel	355254496
+total	354883304
+deal	354512468
+determine	354140864
+evening	353769640
+nor	353399080
+rope	353028004
+cotton	352656832
+apple	352285916
+details	351914264
+entire	351543272
+corn	351172404
+substances	350801548
+smell	350430560
+tools	350059424
+conditions	349688528
+cows	349317484
+track	348946472
+arrived	348575176
+located	348204144
+sir	347833164
+seat	347462200
+division	347090976
+effect	346720048
+underline	346349048
+view	345978584
+recent	345607096
+urban	345236356
+easily	344865840
+difficult	344493608
+object	344122600
+measure	343751376
+science	343380480

backend/app/resources/homophones.json

@@ -0,0 +1,142 @@
+{
+  "_comment": "Each key is a word; value is its homophone group. Used by HomophoneResolver.",
+
+  "their": ["their", "there", "they're"],
+  "there": ["their", "there", "they're"],
+  "they're": ["their", "there", "they're"],
+
+  "your": ["your", "you're"],
+  "you're": ["your", "you're"],
+
+  "its": ["its", "it's"],
+  "it's": ["its", "it's"],
+
+  "to": ["to", "too", "two"],
+  "too": ["to", "too", "two"],
+  "two": ["to", "too", "two"],
+
+  "then": ["then", "than"],
+  "than": ["then", "than"],
+
+  "affect": ["affect", "effect"],
+  "effect": ["affect", "effect"],
+
+  "lose": ["lose", "loose"],
+  "loose": ["lose", "loose"],
+
+  "accept": ["accept", "except"],
+  "except": ["accept", "except"],
+
+  "weather": ["weather", "whether"],
+  "whether": ["weather", "whether"],
+
+  "principal": ["principal", "principle"],
+  "principle": ["principal", "principle"],
+
+  "complement": ["complement", "compliment"],
+  "compliment": ["complement", "compliment"],
+
+  "stationary": ["stationary", "stationery"],
+  "stationery": ["stationary", "stationery"],
+
+  "bare": ["bare", "bear"],
+  "bear": ["bare", "bear"],
+
+  "pore": ["pore", "pour", "poor"],
+  "pour": ["pore", "pour", "poor"],
+  "poor": ["pore", "pour", "poor"],
+
+  "brake": ["brake", "break"],
+  "break": ["brake", "break"],
+
+  "capital": ["capital", "capitol"],
+  "capitol": ["capital", "capitol"],
+
+  "cite": ["cite", "sight", "site"],
+  "sight": ["cite", "sight", "site"],
+  "site": ["cite", "sight", "site"],
+
+  "coarse": ["coarse", "course"],
+  "course": ["coarse", "course"],
+
+  "council": ["council", "counsel"],
+  "counsel": ["council", "counsel"],
+
+  "desert": ["desert", "dessert"],
+  "dessert": ["desert", "dessert"],
+
+  "discreet": ["discreet", "discrete"],
+  "discrete": ["discreet", "discrete"],
+
+  "elicit": ["elicit", "illicit"],
+  "illicit": ["elicit", "illicit"],
+
+  "eminent": ["eminent", "imminent"],
+  "imminent": ["eminent", "imminent"],
+
+  "flair": ["flair", "flare"],
+  "flare": ["flair", "flare"],
+
+  "forward": ["forward", "foreword"],
+  "foreword": ["forward", "foreword"],
+
+  "formally": ["formally", "formerly"],
+  "formerly": ["formally", "formerly"],
+
+  "gorilla": ["gorilla", "guerrilla"],
+  "guerrilla": ["gorilla", "guerrilla"],
+
+  "led": ["led", "lead"],
+  "lead": ["led", "lead"],
+
+  "lightening": ["lightening", "lightning"],
+  "lightning": ["lightening", "lightning"],
+
+  "moral": ["moral", "morale"],
+  "morale": ["moral", "morale"],
+
+  "passed": ["passed", "past"],
+  "past": ["passed", "past"],
+
+  "peace": ["peace", "piece"],
+  "piece": ["peace", "piece"],
+
+  "peak": ["peak", "peek", "pique"],
+  "peek": ["peak", "peek", "pique"],
+  "pique": ["peak", "peek", "pique"],
+
+  "plain": ["plain", "plane"],
+  "plane": ["plain", "plane"],
+
+  "pray": ["pray", "prey"],
+  "prey": ["pray", "prey"],
+
+  "right": ["right", "write", "rite"],
+  "write": ["right", "write", "rite"],
+  "rite": ["right", "write", "rite"],
+
+  "role": ["role", "roll"],
+  "roll": ["role", "roll"],
+
+  "scene": ["scene", "seen"],
+  "seen": ["scene", "seen"],
+
+  "steak": ["steak", "stake"],
+  "stake": ["steak", "stake"],
+
+  "suite": ["suite", "sweet"],
+  "sweet": ["suite", "sweet"],
+
+  "vain": ["vain", "vane", "vein"],
+  "vane": ["vain", "vane", "vein"],
+  "vein": ["vain", "vane", "vein"],
+
+  "waste": ["waste", "waist"],
+  "waist": ["waste", "waist"],
+
+  "who's": ["who's", "whose"],
+  "whose": ["who's", "whose"],
+
+  "which": ["which", "witch"],
+  "witch": ["which", "witch"]
+}

backend/app/utils/text_utils.py

@@ -0,0 +1,104 @@
+"""
+app/utils/text_utils.py
+────────────────────────
+Shared text processing helpers used across the pipeline.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+
+# ── Whitespace normalisation ──────────────────────────────────────────────────
+
+def normalise_whitespace(text: str) -> str:
+    """Collapse multiple spaces / tabs into one; strip leading/trailing."""
+    text = unicodedata.normalize("NFKC", text)   # normalise unicode
+    text = re.sub(r"[ \t]+", " ", text)           # collapse horizontal space
+    text = re.sub(r"\n{3,}", "\n\n", text)        # max two consecutive newlines
+    return text.strip()
+
+
+# ── Sentence splitting ────────────────────────────────────────────────────────
+
+_SENT_BOUNDARY = re.compile(
+    r"(?<=[.!?])\s+(?=[A-Z])"      # punctuation followed by capital
+    r"|(?<=[.!?])\s*$"             # punctuation at end of string
+)
+
+
+def split_into_sentences(text: str) -> list[str]:
+    """
+    Naive but fast sentence splitter.
+    Falls back gracefully for texts without clear boundaries.
+    """
+    # Split on sentence-ending punctuation followed by a space and capital
+    parts = re.split(r"(?<=[.!?])\s+(?=[A-Z\"\'])", text)
+    # Filter empty strings
+    return [p.strip() for p in parts if p.strip()]
+
+
+# ── Word-level diff ───────────────────────────────────────────────────────────
+
+def build_word_diffs(
+    original: str,
+    corrected: str,
+    diff_type: str,
+) -> list[dict]:
+    """
+    Simple LCS-based word-level diff.
+    Returns a list of {original, corrected, type, position} dicts.
+    """
+    ow = original.split()
+    cw = corrected.split()
+
+    # LCS DP table
+    m, n = len(ow), len(cw)
+    dp = [[0] * (n + 1) for _ in range(m + 1)]
+    for i in range(m - 1, -1, -1):
+        for j in range(n - 1, -1, -1):
+            if ow[i].lower() == cw[j].lower():
+                dp[i][j] = dp[i + 1][j + 1] + 1
+            else:
+                dp[i][j] = max(dp[i + 1][j], dp[i][j + 1])
+
+    diffs: list[dict] = []
+    i, j, pos = 0, 0, 0
+
+    while i < m or j < n:
+        if i < m and j < n and ow[i].lower() == cw[j].lower():
+            i += 1; j += 1; pos += 1
+        elif j < n and (i >= m or dp[i + 1][j] <= dp[i][j + 1]):
+            # Insertion in corrected
+            # Pair with previous deletion if it exists and merge into a substitution
+            if diffs and diffs[-1]["position"] == pos - 1 and diffs[-1]["corrected"] == "":
+                diffs[-1]["corrected"] = cw[j]
+            else:
+                diffs.append({
+                    "original": "",
+                    "corrected": cw[j],
+                    "type": diff_type,
+                    "position": pos,
+                })
+            j += 1
+        else:
+            diffs.append({
+                "original": ow[i],
+                "corrected": "",
+                "type": diff_type,
+                "position": pos,
+            })
+            i += 1; pos += 1
+
+    return diffs
+
+
+def count_word_diffs(a: str, b: str) -> int:
+    """Count the number of differing word positions between two strings."""
+    wa, wb = a.split(), b.split()
+    count = abs(len(wa) - len(wb))
+    for x, y in zip(wa, wb):
+        if x.lower() != y.lower():
+            count += 1
+    return count

backend/requirements.txt

@@ -0,0 +1,8 @@
+fastapi==0.104.1
+uvicorn==0.24.0.post1
+pydantic==2.5.2
+pydantic-settings==2.1.0
+loguru==0.7.2
+spacy==3.7.2
+symspellpy==6.7.7
+transformers==4.35.2

backend/tests/test_pipeline.py

@@ -0,0 +1,227 @@
+"""
+tests/test_pipeline.py
+───────────────────────
+Unit + integration tests for the WriteRight NLP pipeline.
+Run with: pytest tests/ -v
+"""
+
+import pytest
+import sys
+import os
+
+# Make sure app is importable
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from app.utils.text_utils import (
+    normalise_whitespace,
+    split_into_sentences,
+    build_word_diffs,
+    count_word_diffs,
+)
+from app.pipeline.homophone_resolver import HomophoneResolver
+from app.config import Settings
+
+
+# ── Fixtures ──────────────────────────────────────────────────────────────────
+
+@pytest.fixture
+def settings():
+    return Settings()
+
+
+@pytest.fixture
+def homophone_resolver(settings):
+    resolver = HomophoneResolver(settings)
+    resolver.load()
+    return resolver
+
+
+# ── text_utils tests ──────────────────────────────────────────────────────────
+
+class TestNormaliseWhitespace:
+    def test_collapses_spaces(self):
+        assert normalise_whitespace("hello   world") == "hello world"
+
+    def test_strips_leading_trailing(self):
+        assert normalise_whitespace("  hello  ") == "hello"
+
+    def test_collapses_tabs(self):
+        assert normalise_whitespace("hello\t\tworld") == "hello world"
+
+    def test_preserves_single_newlines(self):
+        result = normalise_whitespace("line one\nline two")
+        assert "line one" in result and "line two" in result
+
+    def test_collapses_triple_newlines(self):
+        result = normalise_whitespace("a\n\n\n\nb")
+        assert "\n\n\n" not in result
+
+    def test_empty_string(self):
+        assert normalise_whitespace("") == ""
+
+    def test_only_whitespace(self):
+        assert normalise_whitespace("   \t  ") == ""
+
+
+class TestSplitIntoSentences:
+    def test_single_sentence(self):
+        sentences = split_into_sentences("Hello world.")
+        assert len(sentences) == 1
+
+    def test_two_sentences(self):
+        sentences = split_into_sentences("Hello world. My name is Alice.")
+        assert len(sentences) == 2
+
+    def test_question_marks(self):
+        sentences = split_into_sentences("How are you? I am fine.")
+        assert len(sentences) == 2
+
+    def test_exclamation(self):
+        sentences = split_into_sentences("Watch out! There is a bug.")
+        assert len(sentences) == 2
+
+    def test_no_punctuation(self):
+        sentences = split_into_sentences("a simple sentence without end")
+        assert len(sentences) >= 1
+
+    def test_empty_string(self):
+        sentences = split_into_sentences("")
+        assert sentences == []
+
+
+class TestBuildWordDiffs:
+    def test_no_changes(self):
+        diffs = build_word_diffs("hello world", "hello world", "spell")
+        assert len(diffs) == 0
+
+    def test_single_substitution(self):
+        diffs = build_word_diffs("helo world", "hello world", "spell")
+        # Should detect the change
+        assert len(diffs) >= 1
+
+    def test_diff_type_preserved(self):
+        diffs = build_word_diffs("I goes home", "I go home", "grammar")
+        for d in diffs:
+            assert d["type"] == "grammar"
+
+    def test_insertion(self):
+        diffs = build_word_diffs("I very happy", "I am very happy", "grammar")
+        assert len(diffs) >= 1
+
+
+class TestCountWordDiffs:
+    def test_identical(self):
+        assert count_word_diffs("hello world", "hello world") == 0
+
+    def test_one_change(self):
+        assert count_word_diffs("helo world", "hello world") == 1
+
+    def test_length_difference(self):
+        result = count_word_diffs("one two three", "one two three four")
+        assert result >= 1
+
+    def test_empty(self):
+        assert count_word_diffs("", "") == 0
+
+
+# ── Homophone resolver tests ─────────────────────────────────────────────────
+
+class TestHomophoneResolver:
+    def test_your_going(self, homophone_resolver):
+        result = homophone_resolver.resolve("your going to love this")
+        assert "you're" in result["corrected"]
+        assert result["fixes"] >= 1
+
+    def test_their_is(self, homophone_resolver):
+        result = homophone_resolver.resolve("their is a problem")
+        assert "there" in result["corrected"].lower()
+
+    def test_more_then(self, homophone_resolver):
+        result = homophone_resolver.resolve("This is more then enough")
+        assert "than" in result["corrected"]
+
+    def test_no_false_positive(self, homophone_resolver):
+        clean = "There is a cat in their house."
+        result = homophone_resolver.resolve(clean)
+        # Should not mangle correctly used their/there
+        assert result["corrected"] == clean or result["fixes"] == 0
+
+    def test_will_loose(self, homophone_resolver):
+        result = homophone_resolver.resolve("Don't loose your keys")
+        assert "lose" in result["corrected"]
+
+
+# ── Config tests ──────────────────────────────────────────────────────────────
+
+class TestSettings:
+    def test_defaults_exist(self, settings):
+        assert settings.app_name
+        assert settings.app_version
+        assert settings.max_input_length > 0
+
+    def test_model_name_set(self, settings):
+        assert "t5" in settings.model_name.lower()
+
+    def test_spell_edit_distance(self, settings):
+        assert 1 <= settings.spell_max_edit_distance <= 3
+
+
+# ── API integration tests (requires running server) ──────────────────────────
+
+@pytest.mark.asyncio
+class TestAPIIntegration:
+    """
+    These tests hit the actual API. Skip them if the server isn't running.
+    Run with: pytest tests/ -v -m integration
+    """
+
+    @pytest.mark.integration
+    async def test_health_endpoint(self):
+        import httpx
+        async with httpx.AsyncClient(base_url="http://localhost:8000") as client:
+            resp = await client.get("/api/health")
+            assert resp.status_code == 200
+            data = resp.json()
+            assert data["status"] == "ok"
+
+    @pytest.mark.integration
+    async def test_correct_endpoint(self):
+        import httpx
+        async with httpx.AsyncClient(base_url="http://localhost:8000") as client:
+            resp = await client.post(
+                "/api/correct",
+                json={"text": "She dont know wher she goed yesterday."},
+            )
+            assert resp.status_code == 200
+            data = resp.json()
+            assert "corrected" in data
+            assert data["corrected"] != data["original"]
+
+    @pytest.mark.integration
+    async def test_refine_endpoint(self):
+        import httpx
+        async with httpx.AsyncClient(base_url="http://localhost:8000") as client:
+            resp = await client.post(
+                "/api/refine",
+                json={"text": "The meeting was attended by the team.", "style": "professional"},
+            )
+            assert resp.status_code == 200
+            data = resp.json()
+            assert "refined" in data
+            assert "improvements" in data
+
+    @pytest.mark.integration
+    async def test_empty_text_rejected(self):
+        import httpx
+        async with httpx.AsyncClient(base_url="http://localhost:8000") as client:
+            resp = await client.post("/api/correct", json={"text": "  "})
+            assert resp.status_code == 422
+
+    @pytest.mark.integration
+    async def test_stats_endpoint(self):
+        import httpx
+        async with httpx.AsyncClient(base_url="http://localhost:8000") as client:
+            resp = await client.get("/api/stats")
+            assert resp.status_code == 200
+            data = resp.json()
+            assert "total_requests" in data

frontend/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>WriteRight · AI Text Correction</title>
+    <meta name="description" content="WriteRight — intelligent spelling, grammar, and style correction powered by NLP." />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link href="https://fonts.googleapis.com/css2?family=Cormorant+Garamond:ital,wght@0,400;0,600;0,700;1,400;1,600&family=DM+Sans:wght@300;400;500;600&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

frontend/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "writeright-frontend",
+  "version": "2.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.45.0",
+    "axios": "^1.7.2",
+    "framer-motion": "^11.3.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-hot-toast": "^2.4.1"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.0",
+    "autoprefixer": "^10.4.19",
+    "postcss": "^8.4.38",
+    "tailwindcss": "^3.4.4",
+    "vite": "^5.3.1"
+  }
+}

frontend/postcss.config.js

@@ -0,0 +1 @@
+export default { plugins: { tailwindcss: {}, autoprefixer: {} } }

frontend/src/App.jsx

@@ -0,0 +1,52 @@
+/**
+ * App.jsx
+ * ────────
+ * Root shell: ambient background, navbar, page content, toasts.
+ */
+
+import { Toaster } from 'react-hot-toast'
+import { motion } from 'framer-motion'
+import Navbar from './components/Navbar'
+import Home from './pages/Home'
+import { useUI } from './store/UIContext'
+
+export default function App() {
+  const { theme } = useUI()
+
+  return (
+    <div className="app-shell">
+
+      {/* ── Animated ambient background ── */}
+      <div className="ambient" aria-hidden="true">
+        <div className="ambient-orb ambient-orb-1" />
+        <div className="ambient-orb ambient-orb-2" />
+        <div className="ambient-orb ambient-orb-3" />
+      </div>
+      <div className="noise-overlay" aria-hidden="true" />
+
+      {/* ── Navbar ── */}
+      <Navbar />
+
+      {/* ── Page ── */}
+      <main className="page-content" style={{ position: 'relative', zIndex: 1 }}>
+        <Home />
+      </main>
+
+      {/* ── Toast notifications ── */}
+      <Toaster
+        position="bottom-right"
+        toastOptions={{
+          duration: 2600,
+          style: {
+            fontFamily: "'DM Sans', sans-serif",
+            fontSize: '13px',
+            background: 'var(--surface)',
+            color: 'var(--text)',
+            border: '1px solid var(--border)',
+            boxShadow: 'var(--shadow-lg)',
+          },
+        }}
+      />
+    </div>
+  )
+}

frontend/src/components/CorrectionPanel.jsx

@@ -0,0 +1,269 @@
+/**
+ * components/CorrectionPanel.jsx
+ * ───────────────────────────────
+ * Right panel. Features:
+ * - Skeleton loader during processing
+ * - Word-level diff highlighting
+ * - 3D flip card: front = correction, back = refinement
+ * - Metric chips, confidence badge, copy, "Use as Input"
+ */
+
+import { useMemo } from 'react'
+import { motion, AnimatePresence } from 'framer-motion'
+import toast from 'react-hot-toast'
+
+// ── Word diff renderer ──
+function renderDiff(original, diffs) {
+  if (!diffs || diffs.length === 0) return <span>{original}</span>
+
+  const changeMap = {}
+  for (const d of diffs) {
+    if (d.original || d.corrected) changeMap[d.position] = d
+  }
+
+  const tokens = original.split(/(\s+)/)
+  let idx = 0
+  const nodes = []
+
+  tokens.forEach((tok, i) => {
+    if (/^\s+$/.test(tok)) { nodes.push(tok); return }
+    const ch = changeMap[idx]
+    if (ch) {
+      const cls = ch.type === 'homophone' ? 'diff-hom' : 'diff-del'
+      nodes.push(<span key={`d${i}`} className={cls}>{ch.original || tok}</span>)
+      if (ch.corrected) {
+        nodes.push(' ')
+        nodes.push(<span key={`i${i}`} className="diff-ins">{ch.corrected}</span>)
+      }
+    } else {
+      nodes.push(tok)
+    }
+    idx++
+  })
+
+  return <>{nodes}</>
+}
+
+// ── Confidence badge ──
+function ConfBadge({ value }) {
+  const pct   = Math.round(value * 100)
+  const color = pct >= 85 ? 'var(--green)' : pct >= 65 ? 'var(--amber)' : 'var(--red)'
+  const bg    = pct >= 85 ? 'var(--green-soft)' : pct >= 65 ? 'var(--amber-soft)' : 'var(--red-soft)'
+  return (
+    <motion.span 
+      whileHover={{ scale: 1.05 }}
+      style={{ fontSize: 11.5, fontWeight: 600, color, background: bg,
+      padding: '2px 9px', borderRadius: 100, border: `1px solid ${color}`, cursor: 'default' }}>
+      {pct}% confidence
+    </motion.span>
+  )
+}
+
+// ── Skeleton ──
+function Skeleton({ lines = [88, 72, 80, 55, 68] }) {
+  return (
+    <motion.div style={{ padding: '18px' }} initial={{ opacity: 0 }} animate={{ opacity: 1 }}>
+      {lines.map((w, i) => (
+        <motion.div
+          key={i}
+          className="skeleton"
+          style={{ width: `${w}%`, height: 13, marginBottom: 11, borderRadius: 6 }}
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+          transition={{ delay: i * 0.05 }}
+        />
+      ))}
+    </motion.div>
+  )
+}
+
+// ── Copy util ──
+function copyText(text) {
+  navigator.clipboard.writeText(text).then(() => {
+    toast.success('Copied to clipboard', {
+      style: {
+        background: 'var(--green-soft)', color: 'var(--green)',
+        border: '1px solid var(--green)',
+        fontFamily: "'DM Sans',sans-serif", fontSize: '13px',
+      },
+    })
+  })
+}
+
+// ── Card header ──
+function PanelHeader({ title, tagLabel, tagClass, copyValue, extra }) {
+  return (
+    <div className="card-header" style={{ gap: 8 }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+        <span style={{ fontSize: 13, fontWeight: 600, color: 'var(--text)' }}>{title}</span>
+        <span className={`tag ${tagClass}`}>{tagLabel}</span>
+      </div>
+      <div style={{ display: 'flex', gap: 6, alignItems: 'center' }}>
+        {extra}
+        {copyValue && (
+          <motion.button
+            className="btn-ghost"
+            style={{ padding: '4px 10px', fontSize: 12 }}
+            onClick={() => copyText(copyValue)}
+            whileHover={{ scale: 1.05 }}
+            whileTap={{ scale: 0.95 }}
+          >
+            ⎘ Copy
+          </motion.button>
+        )}
+      </div>
+    </div>
+  )
+}
+
+// ── Empty state ──
+function EmptyState() {
+  return (
+    <motion.div
+      className="empty-state"
+      initial={{ opacity: 0, scale: 0.95 }}
+      animate={{ opacity: 1, scale: 1 }}
+      transition={{ duration: 0.5, ease: "easeOut" }}
+    >
+      <div className="empty-icon">✦</div>
+      <p style={{ fontSize: 14, fontWeight: 500, color: 'var(--muted)' }}>
+        Awaiting Text Pipeline
+      </p>
+      <p style={{ fontSize: 12.5, color: 'var(--muted2)', maxWidth: 220, lineHeight: 1.6 }}>
+        Insert text on the left and run diagnostics to see engine evaluations.
+      </p>
+    </motion.div>
+  )
+}
+
+// ── Correction face (front) ──
+function CorrectionFace({ result, loading, onFlipHint }) {
+  const diffNode = useMemo(() => result ? renderDiff(result.original, result.diffs) : null, [result])
+
+  if (loading) return <><PanelHeader title="Neural Diagnostics" tagLabel="Processing…" tagClass="tag-proc" /><Skeleton /></>
+  if (!result) return <EmptyState />
+
+  return (
+    <>
+      <PanelHeader title="Pipeline Results" tagLabel="✓ Resolved" tagClass="tag-spell" copyValue={result.corrected} />
+
+      <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap', padding: '12px 18px 0' }}>
+        {result.spell_fixed > 0 && (
+          <motion.span whileHover={{ scale: 1.05 }} className="chip chip-spell"><span className="chip-dot" />{result.spell_fixed} spelling</motion.span>
+        )}
+        {result.grammar_fixed > 0 && (
+          <motion.span whileHover={{ scale: 1.05 }} className="chip chip-gram"><span className="chip-dot" />{result.grammar_fixed} grammar</motion.span>
+        )}
+        {result.homophone_fixed > 0 && (
+          <motion.span whileHover={{ scale: 1.05 }} className="chip chip-hom"><span className="chip-dot" />{result.homophone_fixed} homophone</motion.span>
+        )}
+        <ConfBadge value={result.confidence} />
+      </div>
+
+      <motion.div
+        style={{ padding: '14px 18px 18px', fontSize: 14.5, lineHeight: 1.9, borderTop: '1px solid var(--divider)', marginTop: 12, whiteSpace: 'pre-wrap', wordBreak: 'break-word', color: 'var(--text)' }}
+        initial={{ opacity: 0, y: 5 }} animate={{ opacity: 1, y: 0 }} transition={{ duration: 0.4 }}
+      >
+        {diffNode}
+      </motion.div>
+
+      <div style={{ margin: '0 18px 12px', padding: '10px 14px', borderRadius: 8, background: 'var(--surface-alt)', border: '1px solid var(--border)', fontSize: 13, color: 'var(--text-2)', lineHeight: 1.7 }}>
+        <span style={{ color: 'var(--green)', marginRight: 6, fontWeight: 600 }}>✓</span>
+        {result.corrected}
+      </div>
+
+      {onFlipHint && (
+        <div style={{ padding: '10px 18px 14px', fontSize: 11.5, color: 'var(--muted2)', borderTop: '1px solid var(--divider)', display: 'flex', alignItems: 'center', gap: 6 }}>
+          <span style={{ fontSize: 13 }}>✦</span> Click <strong style={{ color: 'var(--accent)' }}>Refine Text</strong> to synthesize a stylistic rewrite →
+        </div>
+      )}
+    </>
+  )
+}
+
+// ── Refinement face (back) ──
+function RefinementFace({ result, loading }) {
+  if (loading) return <><PanelHeader title="Stylistic Refinement" tagLabel="Synthesizing…" tagClass="tag-proc" /><Skeleton lines={[90, 78, 85, 72, 60, 82, 50]} /></>
+  if (!result) return null
+
+  return (
+    <>
+      <PanelHeader
+        title="Stylistic Refinement" tagLabel="✦ Synthesized" tagClass="tag-refine" copyValue={result.refined}
+        extra={
+          <motion.button
+            className="btn-ghost" style={{ padding: '4px 10px', fontSize: 12 }}
+            onClick={() => {
+              window.dispatchEvent(new CustomEvent('wr:loadText', { detail: result.refined }))
+              toast.success('Loaded into editor', { style: { background: 'var(--purple-soft)', color: 'var(--purple)', border: '1px solid var(--purple)', fontFamily: "'DM Sans',sans-serif", fontSize: '13px' } })
+            }}
+            whileHover={{ scale: 1.05 }} whileTap={{ scale: 0.95 }}
+          >
+            ↑ Use as Input
+          </motion.button>
+        }
+      />
+
+      {result.improvements?.length > 0 && (
+        <div style={{ padding: '12px 18px 0', display: 'flex', flexDirection: 'column', gap: 6 }}>
+          {result.improvements.map((imp, i) => (
+            <motion.div key={i} className="improvement-item" initial={{ opacity: 0, x: 10 }} animate={{ opacity: 1, x: 0 }} transition={{ delay: i * 0.07 }}>
+              <span className="improvement-icon">✦</span>{imp}
+            </motion.div>
+          ))}
+        </div>
+      )}
+
+      <motion.div
+        className="refined-text" style={{ padding: '16px 18px 20px', borderTop: '1px solid var(--divider)', marginTop: 12 }}
+        initial={{ opacity: 0 }} animate={{ opacity: 1 }} transition={{ delay: 0.2, duration: 0.5 }}
+      >
+        {result.refined}
+      </motion.div>
+
+      <div style={{ padding: '10px 18px 14px', borderTop: '1px solid var(--divider)', display: 'flex', alignItems: 'center', justifyContent: 'space-between', fontSize: 11.5, color: 'var(--muted2)' }}>
+        <span>T5 Transformer Output</span>
+        <span style={{ color: 'var(--purple)' }}>✦ AI-enhanced</span>
+      </div>
+    </>
+  )
+}
+
+// ── Main export ──
+export default function CorrectionPanel({ correctionResult, refineResult, correctionLoading, refineLoading }) {
+  const isFlipped = Boolean(refineResult || refineLoading)
+
+  return (
+    <motion.div initial={{ opacity: 0, x: 28 }} animate={{ opacity: 1, x: 0 }} transition={{ duration: 0.55, ease: [0.22, 1, 0.36, 1], delay: 0.2 }}>
+      
+      <AnimatePresence>
+        {isFlipped && (
+          <motion.div initial={{ opacity: 0, y: -8 }} animate={{ opacity: 1, y: 0 }} exit={{ opacity: 0, y: -8 }} style={{ display: 'flex', alignItems: 'center', gap: 8, marginBottom: 10, fontSize: 12, color: 'var(--purple)', fontWeight: 500 }}>
+            <span style={{ fontSize: 14 }}>✦</span> Viewing refined output <span style={{ color: 'var(--muted2)', fontWeight: 400 }}>· card flipped 180°</span>
+          </motion.div>
+        )}
+      </AnimatePresence>
+
+      <div className="flip-scene" style={{ minHeight: 400 }}>
+        <div className={`flip-card ${isFlipped ? 'flipped' : ''}`}>
+          <div className="flip-face flip-face-front"><CorrectionFace result={correctionResult} loading={correctionLoading} onFlipHint={Boolean(correctionResult)} /></div>
+          <div className="flip-face flip-face-back"><RefinementFace result={refineResult} loading={refineLoading} /></div>
+        </div>
+      </div>
+
+      <AnimatePresence>
+        {isFlipped && correctionResult && (
+          <motion.div initial={{ opacity: 0, y: 8 }} animate={{ opacity: 1, y: 0 }} exit={{ opacity: 0, y: 8 }} style={{ marginTop: 10, display: 'flex', justifyContent: 'flex-end' }}>
+            <motion.button
+              className="btn-ghost" style={{ fontSize: 12, padding: '5px 12px' }}
+              onClick={() => window.dispatchEvent(new CustomEvent('wr:backToCorrection'))}
+              whileHover={{ scale: 1.02 }} whileTap={{ scale: 0.95 }}
+            >
+              ← Back to diagnostics
+            </motion.button>
+          </motion.div>
+        )}
+      </AnimatePresence>
+    </motion.div>
+  )
+}

frontend/src/components/Navbar.jsx

@@ -0,0 +1,49 @@
+/**
+ * components/Navbar.jsx
+ * ─────────────────────
+ * Sticky top bar — Cleaned up to remove unnecessary API health polling.
+ */
+
+import { motion } from 'framer-motion'
+import ThemeToggle from './ThemeToggle'
+
+export default function Navbar() {
+  return (
+    <motion.header
+      className="navbar"
+      initial={{ y: -56, opacity: 0 }}
+      animate={{ y: 0, opacity: 1 }}
+      transition={{ duration: 0.5, ease: [0.22, 1, 0.36, 1] }}
+      style={{ 
+        display: 'flex', 
+        justifyContent: 'space-between', 
+        alignItems: 'center', 
+        padding: '16px 32px', 
+        borderBottom: '1px solid var(--border)',
+        background: 'var(--overlay)',
+        backdropFilter: 'blur(12px)'
+      }}
+    >
+      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+        <span style={{ fontWeight: 700, fontSize: 18, color: 'var(--text)', letterSpacing: '-0.02em' }}>
+          WriteRight
+        </span>
+        <span style={{ 
+          fontSize: 11, 
+          fontWeight: 600,
+          color: 'var(--muted)', 
+          background: 'var(--surface-alt)', 
+          padding: '2px 8px', 
+          borderRadius: 100, 
+          border: '1px solid var(--border)' 
+        }}>
+          v2.0 Engine
+        </span>
+      </div>
+      
+      <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+        <ThemeToggle />
+      </div>
+    </motion.header>
+  )
+}

frontend/src/components/TextEditor.jsx

@@ -0,0 +1,186 @@
+/**
+ * components/TextEditor.jsx
+ * ─────────────────────────
+ * Left panel: textarea, char/word counters, action buttons.
+ * Toggles removed for a cleaner, opinionated UX.
+ */
+
+import { useRef, useState, useEffect } from 'react'
+import { motion, AnimatePresence } from 'framer-motion'
+
+const MAX_CHARS = 4096
+
+const STYLES = ['professional', 'casual', 'academic', 'concise']
+
+export default function TextEditor({ onCorrect, onRefine, onClear, loading, hasResult }) {
+  const [text, setText]       = useState('')
+  const [focused, setFocused] = useState(false)
+  const [style, setStyle]     = useState('professional')
+  const ref = useRef(null)
+
+  // Listen for "use-as-input" event from Home
+  useEffect(() => {
+    function handler(e) {
+      setText(e.detail || '')
+      setTimeout(() => ref.current?.focus(), 100)
+    }
+    window.addEventListener('wr:loadText', handler)
+    return () => window.removeEventListener('wr:loadText', handler)
+  }, [])
+
+  const words = text.trim() ? text.trim().split(/\s+/).length : 0
+  const chars = text.length
+  const pct   = Math.min((chars / MAX_CHARS) * 100, 100)
+
+  function handleChange(e) {
+    if (e.target.value.length <= MAX_CHARS) setText(e.target.value)
+  }
+
+  function handleClear() {
+    setText(''); onClear(); ref.current?.focus()
+  }
+
+  const barColor = pct > 90 ? 'var(--red)' : pct > 70 ? 'var(--amber)'
+    : 'linear-gradient(90deg, var(--accent), var(--accent-2))'
+
+  return (
+    <motion.div
+      initial={{ opacity: 0, x: -28 }}
+      animate={{ opacity: 1, x: 0 }}
+      transition={{ duration: 0.55, ease: [0.22, 1, 0.36, 1], delay: 0.1 }}
+    >
+      {/* ── Main input card ── */}
+      <div className={`card ${focused ? 'focused' : ''} ${loading ? 'processing' : ''}`}
+           style={{ '--ring-color': 'rgba(79,70,229,.2)' }}>
+
+        {/* Card header - simplified */}
+        <div className="card-header" style={{ justifyContent: 'flex-start' }}>
+          <div className="label-row">
+            <span className="label-dot" />
+            Input Text
+          </div>
+        </div>
+
+        {/* Textarea */}
+        <textarea
+          ref={ref}
+          className="editor-textarea"
+          value={text}
+          onChange={handleChange}
+          onFocus={() => setFocused(true)}
+          onBlur={() => setFocused(false)}
+          rows={9}
+          disabled={loading}
+          placeholder={"Paste or type your text here…\n\nTry: 'She dont know wher she goed yesterday, it were a compliceted situaton.'"}
+        />
+
+        {/* Char progress bar */}
+        <div className="char-bar-track">
+          <motion.div
+            className="char-bar-fill"
+            animate={{ width: `${pct}%` }}
+            transition={{ duration: 0.15 }}
+            style={{ background: barColor }}
+          />
+        </div>
+
+        {/* Footer */}
+        <div style={{
+          display: 'flex', alignItems: 'center', justifyContent: 'space-between',
+          padding: '10px 18px',
+        }}>
+          <div style={{ display: 'flex', gap: 14 }}>
+            <span style={{ fontSize: 12, color: 'var(--muted)' }}>
+              Words <strong style={{ color: 'var(--text-2)' }}>{words}</strong>
+            </span>
+            <span style={{ fontSize: 12, color: pct > 90 ? 'var(--red)' : 'var(--muted)' }}>
+              Chars <strong style={{ color: pct > 90 ? 'var(--red)' : 'var(--text-2)' }}>{chars}</strong>
+              <span style={{ color: 'var(--muted2)', marginLeft: 2 }}>/ {MAX_CHARS}</span>
+            </span>
+          </div>
+          <AnimatePresence>
+            {text && (
+              <motion.button
+                className="btn-danger"
+                onClick={handleClear}
+                disabled={loading}
+                initial={{ opacity: 0, scale: 0.8 }}
+                animate={{ opacity: 1, scale: 1 }}
+                exit={{ opacity: 0, scale: 0.8 }}
+                transition={{ duration: 0.15 }}
+              >
+                ✕ Clear
+              </motion.button>
+            )}
+          </AnimatePresence>
+        </div>
+      </div>
+
+      {/* ── Action row ── */}
+      <motion.div
+        style={{ display: 'flex', gap: 10, marginTop: 14, flexWrap: 'wrap', alignItems: 'center' }}
+        initial={{ opacity: 0, y: 10 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ delay: 0.25, duration: 0.4 }}
+      >
+        {/* Correct button */}
+        <motion.button
+          className="btn-primary"
+          onClick={() => !loading && text.trim() && onCorrect(text)}
+          disabled={!text.trim() || loading}
+          whileHover={!loading && text.trim() ? { scale: 1.02, boxShadow: '0 4px 20px rgba(79,70,229,.45)' } : {}}
+          whileTap={{ scale: 0.97 }}
+          style={{ minWidth: 170 }}
+        >
+          {loading
+            ? <><span className="spinner" /> Analysing…</>
+            : <><span style={{ fontSize: 15 }}>⚡</span> Fix Spelling &amp; Grammar</>
+          }
+        </motion.button>
+
+        {/* Refine button + style picker */}
+        <div style={{ display: 'flex', alignItems: 'stretch' }}>
+          <motion.button
+            className="btn-cyan"
+            onClick={() => hasResult && !loading && onRefine(style)}
+            disabled={!hasResult || loading}
+            whileHover={hasResult && !loading ? { scale: 1.02, boxShadow: '0 4px 20px rgba(8,145,178,.4)' } : {}}
+            whileTap={{ scale: 0.97 }}
+            style={{ borderRadius: '10px 0 0 10px', paddingRight: 14 }}
+          >
+            {loading
+              ? <><span className="spinner" /> Refining…</>
+              : <><span style={{ fontSize: 13 }}>✦</span> Refine Text</>
+            }
+          </motion.button>
+          <select
+            value={style}
+            onChange={e => setStyle(e.target.value)}
+            disabled={!hasResult || loading}
+            style={{
+              padding: '0 10px',
+              borderRadius: '0 10px 10px 0',
+              border: '1px solid var(--accent-2)',
+              borderLeft: 'none',
+              background: 'var(--accent-2-soft)',
+              color: hasResult ? 'var(--accent-2)' : 'var(--muted)',
+              fontSize: 12.5,
+              fontFamily: "'DM Sans', sans-serif",
+              cursor: hasResult ? 'pointer' : 'not-allowed',
+              outline: 'none',
+              opacity: hasResult ? 1 : 0.5,
+              transition: 'all 0.25s ease',
+              fontWeight: 500,
+            }}
+          >
+            {STYLES.map(s => (
+              <option key={s} value={s}>
+                {s.charAt(0).toUpperCase() + s.slice(1)}
+              </option>
+            ))}
+          </select>
+        </div>
+      </motion.div>
+    </motion.div>
+  )
+}

frontend/src/components/ThemeToggle.jsx

@@ -0,0 +1,63 @@
+/**
+ * components/ThemeToggle.jsx
+ * ────────────────────────────
+ * Animated sun/moon toggle that switches dark ↔ light mode.
+ */
+
+import { motion, AnimatePresence } from 'framer-motion'
+import { useUI } from '../store/UIContext'
+
+const SunIcon = () => (
+  <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.2" strokeLinecap="round">
+    <circle cx="12" cy="12" r="5"/>
+    <line x1="12" y1="2" x2="12" y2="4"/>
+    <line x1="12" y1="20" x2="12" y2="22"/>
+    <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/>
+    <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/>
+    <line x1="2" y1="12" x2="4" y2="12"/>
+    <line x1="20" y1="12" x2="22" y2="12"/>
+    <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/>
+    <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/>
+  </svg>
+)
+
+const MoonIcon = () => (
+  <svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.2" strokeLinecap="round">
+    <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
+  </svg>
+)
+
+export default function ThemeToggle() {
+  const { theme, toggleTheme } = useUI()
+  const isDark = theme === 'dark'
+
+  return (
+    <motion.button
+      onClick={toggleTheme}
+      className="btn-icon"
+      title={isDark ? 'Switch to light mode' : 'Switch to dark mode'}
+      whileTap={{ scale: 0.9 }}
+      style={{ position: 'relative', width: 34, height: 34 }}
+      aria-label="Toggle theme"
+    >
+      <AnimatePresence mode="wait" initial={false}>
+        <motion.span
+          key={isDark ? 'moon' : 'sun'}
+          initial={{ rotate: -90, opacity: 0, scale: 0.6 }}
+          animate={{ rotate: 0, opacity: 1, scale: 1 }}
+          exit={{ rotate: 90, opacity: 0, scale: 0.6 }}
+          transition={{ duration: 0.22, ease: 'easeOut' }}
+          style={{
+            position: 'absolute',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            color: isDark ? 'var(--accent)' : 'var(--amber)',
+          }}
+        >
+          {isDark ? <MoonIcon /> : <SunIcon />}
+        </motion.span>
+      </AnimatePresence>
+    </motion.button>
+  )
+}

frontend/src/hooks/useTextCorrection.js

@@ -0,0 +1,38 @@
+/**
+ * hooks/useTextCorrection.js
+ * ────────────────────────────
+ * React Query mutation for the /api/correct endpoint.
+ */
+
+import { useMutation } from '@tanstack/react-query'
+import { correctText } from '../services/api'
+import toast from 'react-hot-toast'
+
+export function useTextCorrection() {
+  return useMutation({
+    // Simplified payload: just the text
+    mutationFn: ({ text }) => correctText(text),
+    onSuccess: (data) => {
+      const total = (data.spell_fixed || 0) + (data.grammar_fixed || 0) + (data.homophone_fixed || 0)
+      if (total === 0) {
+        toast('No errors found — your text looks great!', {
+          icon: '✨',
+          style: getToastStyle('green'),
+        })
+      }
+    },
+    onError: (err) => {
+      toast.error(err.message || 'Correction failed.', {
+        style: getToastStyle('red'),
+      })
+    },
+  })
+}
+
+function getToastStyle(color) {
+  const map = {
+    green: { background: 'var(--green-soft)', color: 'var(--green)', border: '1px solid var(--green)' },
+    red:   { background: 'var(--red-soft)',   color: 'var(--red)',   border: '1px solid var(--red)' },
+  }
+  return { ...map[color], fontFamily: "'DM Sans', sans-serif", fontSize: '13px' }
+}

frontend/src/hooks/useTextRefinement.js

@@ -0,0 +1,26 @@
+/**
+ * hooks/useTextRefinement.js
+ * ───────────────────────────
+ * React Query mutation for the /api/refine endpoint.
+ */
+
+import { useMutation } from '@tanstack/react-query'
+import { refineText } from '../services/api'
+import toast from 'react-hot-toast'
+
+export function useTextRefinement() {
+  return useMutation({
+    mutationFn: ({ text, style = 'professional' }) => refineText(text, style),
+    onError: (err) => {
+      toast.error(err.message || 'Refinement failed.', {
+        style: {
+          background: 'var(--red-soft)',
+          color: 'var(--red)',
+          border: '1px solid var(--red)',
+          fontFamily: "'DM Sans', sans-serif",
+          fontSize: '13px',
+        },
+      })
+    },
+  })
+}

frontend/src/main.jsx

@@ -0,0 +1,23 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { UIProvider } from './store/UIContext'
+import App from './App'
+import './styles/globals.css'
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    mutations: { retry: 0 },
+    queries:   { retry: 1, staleTime: 30_000 },
+  },
+})
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <UIProvider>
+        <App />
+      </UIProvider>
+    </QueryClientProvider>
+  </React.StrictMode>
+)

frontend/src/pages/Home.jsx

@@ -0,0 +1,275 @@
+/**
+ * pages/Home.jsx
+ * ──────────────
+ * Split-panel layout. Left = TextEditor, Right = CorrectionPanel.
+ * Hero title with scroll-based parallax inspired by Chrome's download UX.
+ */
+
+import { useState, useCallback, useEffect, useRef } from 'react'
+import toast from 'react-hot-toast'
+import { motion, useScroll, useTransform, useSpring, AnimatePresence } from 'framer-motion'
+import TextEditor from '../components/TextEditor'
+import CorrectionPanel from '../components/CorrectionPanel'
+import { useTextCorrection } from '../hooks/useTextCorrection'
+import { useTextRefinement } from '../hooks/useTextRefinement'
+
+const HERO_TAGS = ['spaCy', 'SymSpell', 'T5 Transformer', 'FastAPI', 'React 18']
+
+export default function Home() {
+  const heroRef = useRef(null)
+  const { scrollY } = useScroll()
+
+  // Scroll parallax: title drifts up slightly and fades as user scrolls
+  const rawY  = useTransform(scrollY, [0, 200], [0, -40])
+  const rawOp = useTransform(scrollY, [0, 160], [1, 0])
+  const heroY  = useSpring(rawY,  { stiffness: 120, damping: 22 })
+  const heroOp = useSpring(rawOp, { stiffness: 120, damping: 22 })
+
+  // RQ mutations
+  const {
+    mutate: correctMutate,
+    data: correctionResult,
+    isPending: correctionLoading,
+    reset: resetCorrection,
+  } = useTextCorrection()
+
+  const {
+    mutate: refineMutate,
+    data: refineResult,
+    isPending: refineLoading,
+    reset: resetRefinement,
+  } = useTextRefinement()
+
+  // Listen for "back to correction" event from CorrectionPanel
+  useEffect(() => {
+    function handler() { resetRefinement() }
+    window.addEventListener('wr:backToCorrection', handler)
+    return () => window.removeEventListener('wr:backToCorrection', handler)
+  }, [resetRefinement])
+
+  const handleCorrect = useCallback((text, pipeline) => {
+    resetRefinement()
+    correctMutate({ text, pipeline })
+  }, [correctMutate, resetRefinement])
+
+  const handleRefine = useCallback((style) => {
+    if (!correctionResult?.corrected) return
+    refineMutate({ text: correctionResult.corrected, style })
+  }, [correctionResult, refineMutate])
+
+  const handleClear = useCallback(() => {
+    resetCorrection()
+    resetRefinement()
+  }, [resetCorrection, resetRefinement])
+
+  const isLoading = correctionLoading || refineLoading
+
+  return (
+    <div style={{ position: 'relative', zIndex: 1 }}>
+
+      {/* ══════════ HERO ══════════ */}
+      <motion.div
+        ref={heroRef}
+        style={{ y: heroY, opacity: heroOp }}
+        initial={{ opacity: 0, y: 24 }}
+        animate={{ opacity: 1, y: 0 }}
+        transition={{ duration: 0.7, ease: [0.22, 1, 0.36, 1] }}
+      >
+        <div style={{ textAlign: 'center', padding: '48px 0 36px' }}>
+          {/* Eyebrow */}
+          <motion.div
+            initial={{ opacity: 0, y: 10 }}
+            animate={{ opacity: 1, y: 0 }}
+            transition={{ delay: 0.1 }}
+            style={{
+              display: 'inline-flex', alignItems: 'center', gap: 8,
+              padding: '5px 14px', borderRadius: 100,
+              border: '1px solid var(--border2)',
+              background: 'var(--surface-alt)',
+              fontSize: 11, fontWeight: 600, letterSpacing: '0.07em',
+              color: 'var(--muted)', textTransform: 'uppercase',
+              marginBottom: 20,
+            }}
+          >
+            <span style={{ color: 'var(--accent)', fontSize: 13 }}>✦</span>
+            AI Writing Assistant
+          </motion.div>
+
+          {/* Main title */}
+          <motion.h1
+            className="hero-display"
+            initial={{ opacity: 0, y: 20 }}
+            animate={{ opacity: 1, y: 0 }}
+            transition={{ delay: 0.18, duration: 0.65, ease: [0.22, 1, 0.36, 1] }}
+          >
+            Write<em>Right</em>
+          </motion.h1>
+
+          {/* Subtitle */}
+          <motion.p
+            className="hero-sub"
+            initial={{ opacity: 0, y: 14 }}
+            animate={{ opacity: 1, y: 0 }}
+            transition={{ delay: 0.28, duration: 0.55 }}
+          >
+            Paste any text. Fix spelling, resolve grammar, and refine style —
+            powered by spaCy, SymSpell, and a T5 transformer.
+          </motion.p>
+
+          {/* Tech stack tags */}
+          <motion.div
+            style={{ display: 'flex', gap: 6, justifyContent: 'center', flexWrap: 'wrap', marginTop: 20 }}
+            initial={{ opacity: 0 }}
+            animate={{ opacity: 1 }}
+            transition={{ delay: 0.4 }}
+          >
+            {HERO_TAGS.map((tag, i) => (
+              <motion.span
+                key={tag}
+                style={{
+                  padding: '3px 11px', borderRadius: 100,
+                  border: '1px solid var(--border)',
+                  background: 'var(--surface-alt)',
+                  fontSize: 11, fontWeight: 500, color: 'var(--muted2)',
+                  letterSpacing: '0.04em',
+                }}
+                initial={{ opacity: 0, y: 8 }}
+                animate={{ opacity: 1, y: 0 }}
+                transition={{ delay: 0.42 + i * 0.06 }}
+              >
+                {tag}
+              </motion.span>
+            ))}
+          </motion.div>
+        </div>
+      </motion.div>
+
+      {/* ══════════ DIVIDER ══════════ */}
+      <motion.div
+        className="divider-text"
+        style={{ marginBottom: 0, color: 'var(--muted2)', fontSize: 10.5 }}
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        transition={{ delay: 0.55 }}
+      >
+        Start editing
+      </motion.div>
+
+      {/* ══════════ SPLIT GRID ══════════ */}
+      <div className="split-grid" style={{ marginTop: 20 }}>
+
+        {/* LEFT — Editor */}
+        <TextEditor
+          onCorrect={handleCorrect}
+          onRefine={handleRefine}
+          onClear={handleClear}
+          loading={isLoading}
+          hasResult={Boolean(correctionResult)}
+        />
+
+        {/* RIGHT — Results */}
+        <CorrectionPanel
+          correctionResult={correctionResult}
+          refineResult={refineResult}
+          correctionLoading={correctionLoading}
+          refineLoading={refineLoading}
+          onUseRefined={() => {}}
+        />
+
+      </div>
+      {/* ══════════ ACADEMIC EVALUATION METRICS DASHBOARD ══════════ */}
+      <AnimatePresence>
+        {correctionResult && (
+          <motion.div
+            initial={{ opacity: 0, y: 30, scale: 0.98 }}
+            animate={{ opacity: 1, y: 0, scale: 1 }}
+            exit={{ opacity: 0, y: 20, scale: 0.98 }}
+            transition={{ duration: 0.6, ease: [0.22, 1, 0.36, 1] }}
+            style={{ marginTop: '32px' }}
+          >
+            <div className="card" style={{ padding: '32px', background: 'var(--surface)' }}>
+              <div style={{ display: 'flex', alignItems: 'center', gap: 10, marginBottom: '24px', borderBottom: '1px solid var(--border)', paddingBottom: '16px' }}>
+                <span className="label-dot" style={{ background: 'var(--purple)', width: 8, height: 8 }} />
+                <h2 style={{ fontSize: '18px', fontWeight: 700, letterSpacing: '-0.01em', color: 'var(--text)' }}>
+                  Text Evaluation Metrics
+                </h2>
+              </div>
+              
+              {/* Data Calculation (Handled inline for the UI) */}
+              {(() => {
+                const errors = (correctionResult.spell_fixed || 0) + (correctionResult.grammar_fixed || 0) + (correctionResult.homophone_fixed || 0);
+                const words = correctionResult.original ? correctionResult.original.trim().split(/\s+/).length : 1;
+                
+                // NEW FORMULA: Accuracy Ratio (Words / (Words + Errors))
+                const qualityScore = Math.round((words / (words + errors)) * 100);
+const burdenScore = Math.round((words -errors) / words)*100;
+                return (
+                  <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))', gap: '24px' }}>
+                    
+                    {/* Panel 1: User Text Quality Score */}
+                    <div style={{ padding: '24px', background: 'var(--surface-alt)', borderRadius: '12px', border: '1px solid var(--border)' }}>
+                      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start' }}>
+                        <div>
+                          <span style={{ fontSize: '14px', fontWeight: 600, color: 'var(--text-2)' }}>Accuracy Ratio Score</span>
+                          <p style={{ fontSize: '12px', color: 'var(--muted)', marginTop: '4px' }}>Proportional evaluation of input validity.</p>
+                        </div>
+                        <div style={{ display: 'flex', alignItems: 'baseline', gap: '2px' }}>
+                          <span style={{ fontSize: '42px', fontWeight: 700, color: qualityScore > 80 ? 'var(--green)' : qualityScore > 50 ? 'var(--amber)' : 'var(--red)' }}>
+                            {qualityScore}
+                          </span>
+                          <span style={{ fontSize: '16px', fontWeight: 600, color: 'var(--muted)' }}>/100</span>
+                        </div>
+                      </div>
+                      
+                      {/* Formula Display */}
+                      <div style={{ marginTop: '20px', padding: '12px', background: 'var(--bg)', borderRadius: '8px', border: '1px dashed var(--border2)', fontFamily: "'JetBrains Mono', monospace", fontSize: '12px', color: 'var(--muted)' }}>
+                        <div style={{ marginBottom: '6px', color: 'var(--text-2)', fontWeight: 500 }}>Applied Formula:</div>
+                        <div>Score = (Words / (Words + Errors)) * 100</div>
+                        <div style={{ marginTop: '6px', color: 'var(--accent)' }}>Calculation: ({words} / ({words} + {errors})) * 100</div>
+                      </div>
+                    </div>
+
+                    {/* Panel 2: Error Density (Rho) */}
+                    {/* Panel 2: Correction Burden */}
+                    <div style={{ padding: '24px', background: 'var(--surface-alt)', borderRadius: '12px', border: '1px solid var(--border)' }}>
+                      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'flex-start' }}>
+                        <div>
+                          <span style={{ fontSize: '14px', fontWeight: 600, color: 'var(--text-2)' }}>Correction Burden</span>
+                          <p style={{ fontSize: '12px', color: 'var(--muted)', marginTop: '4px' }}>Projected number of errors per 100 words.</p>
+                        </div>
+                        <div style={{ display: 'flex', alignItems: 'baseline', gap: '2px' }}>
+                          <span style={{ fontSize: '42px', fontWeight: 700, color: 'var(--accent)' }}>
+                            {burdenScore}
+                          </span>
+                          <span style={{ fontSize: '14px', fontWeight: 600, color: 'var(--muted)', marginLeft: '4px' }}>errors</span>
+                        </div>
+                      </div>
+                      
+                      {/* Formula Display */}
+                      <div style={{ marginTop: '20px', padding: '12px', background: 'var(--bg)', borderRadius: '8px', border: '1px dashed var(--border2)', fontFamily: "'JetBrains Mono', monospace", fontSize: '12px', color: 'var(--muted)' }}>
+                        <div style={{ marginBottom: '6px', color: 'var(--text-2)', fontWeight: 500 }}>Applied Formula:</div>
+                        <div>Burden = (Total Errors / Total Words) * 100</div>
+                        <div style={{ marginTop: '6px', color: 'var(--accent)' }}>Calculation: ({errors} / {words}) * 100</div>
+                      </div>
+                    </div>
+
+                  </div>
+                );
+              })()}
+            </div>
+          </motion.div>
+        )}
+      </AnimatePresence>
+
+      {/* Footer */}
+      <motion.p
+        style={{ textAlign: 'center', marginTop: 64, fontSize: 11.5, color: 'var(--muted2)' }}
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        transition={{ delay: 1.2 }}
+      >
+        CVR College of Engineering · CSE(DS) · NLP Auto-Corrector
+      </motion.p>
+    </div>
+  )
+}

frontend/src/services/api.js

@@ -0,0 +1,47 @@
+/**
+ * services/api.js
+ * ─────────────────
+ * Axios wrapper for all WriteRight endpoints.
+ */
+
+import axios from 'axios'
+
+const BASE_URL = import.meta.env.VITE_API_URL ?? 'http://localhost:8000'
+
+const http = axios.create({
+  baseURL: BASE_URL,
+  timeout: 60_000,
+  headers: { 'Content-Type': 'application/json' },
+})
+
+http.interceptors.response.use(
+  res => res,
+  err => {
+    const message =
+      err?.response?.data?.detail ||
+      err?.response?.data?.message ||
+      err?.message || 'Unknown error'
+    return Promise.reject(new Error(message))
+  }
+)
+
+export async function correctText(text) {
+  // Removed all pipeline toggles for a cleaner, unified NLP pass
+  const { data } = await http.post('/api/correct', { text })
+  return data
+}
+
+export async function refineText(text, style = 'professional') {
+  const { data } = await http.post('/api/refine', { text, style })
+  return data
+}
+
+export async function getHealth() {
+  const { data } = await http.get('/api/health')
+  return data
+}
+
+export async function getStats() {
+  const { data } = await http.get('/api/stats')
+  return data
+}

frontend/src/store/UIContext.jsx

@@ -0,0 +1,50 @@
+/**
+ * store/UIContext.jsx
+ * ─────────────────────
+ * Provides:
+ *   - theme: 'light' | 'dark' (persisted to localStorage)
+ *   - toggleTheme()
+ *   - mode: 'idle' | 'correction' | 'refine'
+ *   - setMode()
+ */
+
+import { createContext, useContext, useEffect, useState, useCallback } from 'react'
+
+const UIContext = createContext(null)
+
+export function UIProvider({ children }) {
+  const [theme, setTheme] = useState(() => {
+    const saved = localStorage.getItem('wr-theme')
+    if (saved) return saved
+    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+  })
+
+  const [mode, setMode] = useState('idle')
+
+  // Apply theme class to <html>
+  useEffect(() => {
+    const root = document.documentElement
+    if (theme === 'dark') {
+      root.classList.add('dark')
+    } else {
+      root.classList.remove('dark')
+    }
+    localStorage.setItem('wr-theme', theme)
+  }, [theme])
+
+  const toggleTheme = useCallback(() => {
+    setTheme(t => t === 'light' ? 'dark' : 'light')
+  }, [])
+
+  return (
+    <UIContext.Provider value={{ theme, toggleTheme, mode, setMode }}>
+      {children}
+    </UIContext.Provider>
+  )
+}
+
+export function useUI() {
+  const ctx = useContext(UIContext)
+  if (!ctx) throw new Error('useUI must be inside UIProvider')
+  return ctx
+}

frontend/src/styles/globals.css

@@ -0,0 +1,308 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+/* ══════════════════════════════════════════════════
+   DESIGN TOKENS — LIGHT MODE (default)
+══════════════════════════════════════════════════ */
+@layer base {
+  :root {
+    /* Surfaces */
+    --bg:          #f7f6f3;
+    --bg-alt:      #efede8;
+    --surface:     #ffffff;
+    --surface-alt: #f4f3f0;
+    --overlay:     rgba(247,246,243,0.85);
+
+    /* Borders */
+    --border:      #e2dfd8;
+    --border2:     #cdc9c0;
+    --divider:     #e8e5df;
+
+    /* Text */
+    --text:        #1c1a17;
+    --text-2:      #3d3a34;
+    --muted:       #7c7870;
+    --muted2:      #a09b93;
+    --placeholder: #b8b4ad;
+
+    /* Accent palette — indigo-to-teal */
+    --accent:      #4f46e5;
+    --accent-soft: #eef2ff;
+    --accent-2:    #0891b2;
+    --accent-2-soft: #ecfeff;
+
+    /* Semantic */
+    --green:       #059669;
+    --green-soft:  #d1fae5;
+    --red:         #dc2626;
+    --red-soft:    #fee2e2;
+    --amber:       #d97706;
+    --amber-soft:  #fef3c7;
+    --purple:      #7c3aed;
+    --purple-soft: #ede9fe;
+
+    /* Shadows */
+    --shadow-sm:   0 1px 3px rgba(0,0,0,.06), 0 1px 2px rgba(0,0,0,.04);
+    --shadow-md:   0 4px 16px rgba(0,0,0,.08), 0 2px 6px rgba(0,0,0,.04);
+    --shadow-lg:   0 12px 40px rgba(0,0,0,.10), 0 4px 12px rgba(0,0,0,.06);
+    --shadow-card: 0 0 0 1px var(--border), var(--shadow-md);
+
+    /* Ring */
+    --ring-color:  rgba(79,70,229,.25);
+
+    /* Flip card BG */
+    --flip-front:  #ffffff;
+    --flip-back:   #f0eeff;
+  }
+
+  /* ══════════════════════════════════════
+     DARK MODE
+  ══════════════════════════════════════ */
+  .dark {
+    --bg:          #0f0f14;
+    --bg-alt:      #13131a;
+    --surface:     #18181f;
+    --surface-alt: #1e1e28;
+    --overlay:     rgba(15,15,20,0.88);
+
+    --border:      #252530;
+    --border2:     #32323e;
+    --divider:     #1f1f28;
+
+    --text:        #f0eee8;
+    --text-2:      #c8c4bc;
+    --muted:       #6b6870;
+    --muted2:      #4e4c55;
+    --placeholder: #3a3840;
+
+    --accent:      #818cf8;
+    --accent-soft: #1e1e38;
+    --accent-2:    #22d3ee;
+    --accent-2-soft: #0e2028;
+
+    --green:       #34d399;
+    --green-soft:  #0a2018;
+    --red:         #f87171;
+    --red-soft:    #2a0f0f;
+    --amber:       #fbbf24;
+    --amber-soft:  #2a1a08;
+    --purple:      #c084fc;
+    --purple-soft: #1a0f2a;
+
+    --shadow-sm:   0 1px 3px rgba(0,0,0,.3);
+    --shadow-md:   0 4px 20px rgba(0,0,0,.4);
+    --shadow-lg:   0 12px 48px rgba(0,0,0,.5);
+    --shadow-card: 0 0 0 1px var(--border), var(--shadow-md);
+
+    --ring-color:  rgba(129,140,248,.3);
+
+    --flip-front:  #18181f;
+    --flip-back:   #14102a;
+  }
+
+  /* ── Base resets ── */
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+  html { scroll-behavior: smooth; font-size: 16px; }
+
+  body {
+    background-color: var(--bg);
+    color: var(--text);
+    font-family: 'DM Sans', sans-serif;
+    min-height: 100vh;
+    overflow-x: hidden;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    transition: background-color 0.35s ease, color 0.35s ease;
+  }
+
+  ::selection { background: var(--accent-soft); color: var(--accent); }
+
+  ::-webkit-scrollbar { width: 5px; }
+  ::-webkit-scrollbar-track { background: transparent; }
+  ::-webkit-scrollbar-thumb { background: var(--border2); border-radius: 10px; }
+}
+
+/* ══════════════════════════════════════════════════
+   COMPONENT CLASSES
+══════════════════════════════════════════════════ */
+@layer components {
+
+  /* ── Layout ── */
+  .app-shell {
+    position: relative;
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+  }
+
+  .page-content {
+    flex: 1;
+    max-width: 1280px;
+    margin: 0 auto;
+    padding: 0 24px 80px;
+    width: 100%;
+  }
+
+  /* ── Split grid ── */
+  .split-grid {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 24px;
+    align-items: start;
+    margin-top: 32px;
+  }
+
+  @media (max-width: 900px) {
+    .split-grid { grid-template-columns: 1fr; }
+  }
+
+  /* ── Ambient background ── */
+  .ambient {
+    position: fixed; inset: 0;
+    pointer-events: none; z-index: 0;
+    overflow: hidden;
+  }
+
+  .ambient-orb {
+    position: absolute;
+    border-radius: 50%;
+    filter: blur(80px);
+    opacity: 0.5;
+    animation: float 8s ease-in-out infinite;
+  }
+  .dark .ambient-orb { opacity: 0.18; }
+
+  .ambient-orb-1 { width: 500px; height: 500px; background: radial-gradient(circle, #c7d2fe, #a5b4fc, transparent 70%); top: -100px; left: -150px; animation-delay: 0s; }
+  .ambient-orb-2 { width: 400px; height: 400px; background: radial-gradient(circle, #a5f3fc, #67e8f9, transparent 70%); bottom: -80px; right: -120px; animation-delay: -3s; }
+  .ambient-orb-3 { width: 300px; height: 300px; background: radial-gradient(circle, #ddd6fe, #c4b5fd, transparent 70%); top: 40%; left: 60%; animation-delay: -5s; }
+
+  .noise-overlay {
+    position: fixed; inset: 0; z-index: 0; pointer-events: none; opacity: 0.025;
+    background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");
+    background-repeat: repeat; background-size: 128px;
+  }
+
+  /* ── Navbar ── */
+  .navbar {
+    position: sticky; top: 0; z-index: 100;
+    background: var(--overlay); border-bottom: 1px solid var(--border);
+    backdrop-filter: blur(16px) saturate(160%); -webkit-backdrop-filter: blur(16px) saturate(160%);
+    transition: background 0.35s ease, border-color 0.35s ease;
+  }
+
+  /* ── Hero typography ── */
+  .hero-display {
+    font-family: 'Cormorant Garamond', serif;
+    font-size: clamp(3rem, 7vw, 5.5rem);
+    font-weight: 700; line-height: 1.05; letter-spacing: -0.02em; color: var(--text);
+    transition: color 0.35s ease;
+  }
+  .hero-display em {
+    font-style: italic; font-weight: 400; background: linear-gradient(135deg, var(--accent) 0%, var(--accent-2) 100%);
+    background-size: 200% 200%; -webkit-background-clip: text; -webkit-text-fill-color: transparent; background-clip: text;
+    animation: gradientX 5s ease infinite;
+  }
+  .hero-sub { font-size: 15px; color: var(--muted); font-weight: 400; max-width: 460px; line-height: 1.7; margin: 12px auto 0; }
+
+  /* ── Cards ── */
+  .card {
+    background: var(--surface); border: 1px solid var(--border); border-radius: 16px;
+    box-shadow: var(--shadow-card); transition: background 0.35s ease, border-color 0.35s ease, box-shadow 0.25s ease; overflow: hidden;
+  }
+  .card:hover { box-shadow: var(--shadow-lg); }
+  .card.focused { border-color: var(--accent); box-shadow: 0 0 0 3px var(--ring-color), var(--shadow-md); }
+  .card.processing { --ring-color: rgba(79,70,229,.3); animation: pulseRing 2s ease-in-out infinite; border-color: var(--accent); }
+  .dark .card.processing { --ring-color: rgba(129,140,248,.25); }
+
+  .card-header {
+    display: flex; align-items: center; justify-content: space-between; padding: 14px 18px;
+    border-bottom: 1px solid var(--divider); background: var(--surface-alt);
+  }
+
+  /* ── Flip card ── */
+  .flip-scene { perspective: 1200px; }
+  .flip-card { position: relative; transform-style: preserve-3d; transition: transform 0.7s cubic-bezier(.34,.14,.4,1); }
+  .flip-card.flipped { transform: rotateY(180deg); }
+  .flip-face { backface-visibility: hidden; -webkit-backface-visibility: hidden; border-radius: 16px; overflow: hidden; }
+  .flip-face-front { background: var(--flip-front); border: 1px solid var(--border); box-shadow: var(--shadow-card); transition: background 0.35s ease, border-color 0.35s ease; }
+  .flip-face-back { position: absolute; inset: 0; background: var(--flip-back); border: 1px solid var(--accent); box-shadow: 0 0 0 1px var(--accent), var(--shadow-md); transform: rotateY(180deg); transition: background 0.35s ease; }
+
+  /* ── Buttons ── */
+  .btn {
+    display: inline-flex; align-items: center; gap: 7px; font-family: 'DM Sans', sans-serif; font-size: 13.5px;
+    font-weight: 500; border-radius: 10px; cursor: pointer; border: none; transition: all 0.18s cubic-bezier(.22,1,.36,1);
+    position: relative; overflow: hidden; white-space: nowrap; user-select: none;
+  }
+  .btn::before { content: ''; position: absolute; inset: 0; background: linear-gradient(180deg, rgba(255,255,255,.1) 0%, transparent 100%); opacity: 0; transition: opacity 0.15s; }
+  .btn:hover::before { opacity: 1; }
+  .btn:active { transform: scale(0.97); }
+  .btn:disabled { opacity: 0.45; cursor: not-allowed; pointer-events: none; }
+
+  .btn-primary { padding: 10px 20px; background: var(--accent); color: white; box-shadow: 0 2px 12px rgba(79,70,229,.35); }
+  .btn-primary:hover { background: #4338ca; box-shadow: 0 4px 20px rgba(79,70,229,.45); transform: translateY(-1px); }
+  
+  .btn-cyan { padding: 10px 20px; background: var(--accent-2); color: white; box-shadow: 0 2px 12px rgba(8,145,178,.3); }
+  .btn-cyan:hover { background: #0e7490; box-shadow: 0 4px 20px rgba(8,145,178,.4); transform: translateY(-1px); }
+
+  .btn-ghost { padding: 7px 14px; background: transparent; border: 1px solid var(--border2); color: var(--muted); }
+  .btn-ghost:hover { border-color: var(--accent); color: var(--accent); background: var(--accent-soft); }
+
+  .btn-danger { padding: 7px 12px; font-size: 12.5px; background: transparent; border: 1px solid transparent; color: var(--muted); }
+  .btn-danger:hover { border-color: var(--red); color: var(--red); background: var(--red-soft); }
+
+  .btn-icon { padding: 7px; background: transparent; border: 1px solid var(--border); color: var(--muted); border-radius: 8px; }
+  .btn-icon:hover { background: var(--surface-alt); color: var(--text); border-color: var(--border2); }
+
+  /* ── Textarea ── */
+  .editor-textarea {
+    width: 100%; background: transparent; border: none; outline: none; resize: none; color: var(--text);
+    font-family: 'DM Sans', sans-serif; font-size: 15px; line-height: 1.85; padding: 16px 18px; transition: color 0.35s ease;
+  }
+  .editor-textarea::placeholder { color: var(--placeholder); }
+
+  /* ── Progress bar ── */
+  .char-bar-track { height: 2px; background: var(--divider); margin: 0 18px; border-radius: 2px; overflow: hidden; }
+  .char-bar-fill { height: 100%; border-radius: 2px; transition: width 0.15s ease, background 0.3s ease; }
+
+  /* ── Skeleton ── */
+  .skeleton {
+    border-radius: 6px; background-size: 200% 100%; animation: shimmer 1.7s infinite;
+    background: linear-gradient(90deg, var(--surface-alt) 25%, var(--border) 50%, var(--surface-alt) 75%);
+  }
+
+  /* ── Diff highlights ── */
+  .diff-del { background: var(--red-soft); color: var(--red); text-decoration: line-through; text-decoration-color: var(--red); border-radius: 3px; padding: 0 3px; font-size: 0.95em; }
+  .diff-ins { background: var(--green-soft); color: var(--green); border-radius: 3px; padding: 0 3px; font-weight: 500; }
+  .diff-hom { background: var(--amber-soft); color: var(--amber); border-radius: 3px; padding: 0 3px; border-bottom: 1.5px dashed var(--amber); }
+
+  /* ── Chips & Tags ── */
+  .chip { display: inline-flex; align-items: center; gap: 5px; padding: 3px 10px; border-radius: 100px; font-size: 11.5px; font-weight: 500; cursor: default; }
+  .chip-dot { width: 5px; height: 5px; border-radius: 50%; background: currentColor; }
+  .chip-spell { background: var(--green-soft); color: var(--green); }
+  .chip-gram { background: var(--accent-soft); color: var(--accent); }
+  .chip-hom { background: var(--amber-soft); color: var(--amber); }
+
+  .tag { display: inline-flex; align-items: center; padding: 2px 8px; border-radius: 100px; font-size: 10px; font-weight: 600; letter-spacing: 0.05em; text-transform: uppercase; border: 1px solid currentColor; }
+  .tag-spell { color: var(--green); background: var(--green-soft); border-color: var(--green-soft); }
+  .tag-refine { color: var(--purple); background: var(--purple-soft); border-color: var(--purple-soft); }
+  .tag-proc { color: var(--muted); background: var(--surface-alt); border-color: var(--border); }
+
+  /* ── Utilities ── */
+  .label-row { display: flex; align-items: center; gap: 6px; font-size: 10.5px; font-weight: 600; letter-spacing: 0.08em; text-transform: uppercase; color: var(--muted2); }
+  .label-dot { width: 5px; height: 5px; border-radius: 50%; background: var(--accent); flex-shrink: 0; }
+
+  .spinner { width: 15px; height: 15px; border-radius: 50%; border: 2px solid rgba(255,255,255,0.25); border-top-color: rgba(255,255,255,0.9); animation: spin 0.65s linear infinite; flex-shrink: 0; }
+  @keyframes spin { to { transform: rotate(360deg); } }
+
+  .divider-text { display: flex; align-items: center; gap: 12px; font-size: 11px; letter-spacing: 0.06em; color: var(--muted2); text-transform: uppercase; }
+  .divider-text::before, .divider-text::after { content: ''; flex: 1; height: 1px; background: var(--divider); }
+
+  .improvement-item { display: flex; align-items: flex-start; gap: 8px; padding: 8px 10px; border-radius: 8px; font-size: 13px; color: var(--text-2); background: var(--surface-alt); border: 1px solid var(--border); line-height: 1.5; }
+  .improvement-icon { color: var(--purple); flex-shrink: 0; margin-top: 1px; font-size: 14px; }
+
+  .empty-state { display: flex; flex-direction: column; align-items: center; justify-content: center; padding: 60px 24px; text-align: center; gap: 12px; color: var(--muted2); }
+  .empty-icon { font-size: 40px; opacity: 0.3; animation: float 4s ease-in-out infinite; }
+
+  .refined-text { font-family: 'Cormorant Garamond', serif; font-size: 17px; line-height: 1.9; color: var(--text); white-space: pre-wrap; word-break: break-word; transition: color 0.35s ease; }
+}

frontend/tailwind.config.js

@@ -0,0 +1,45 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  darkMode: 'class',
+  content: ['./index.html', './src/**/*.{js,jsx,ts,tsx}'],
+  theme: {
+    extend: {
+      fontFamily: {
+        display: ["'Cormorant Garamond'", 'Georgia', 'serif'],
+        body:    ["'DM Sans'", 'sans-serif'],
+        mono:    ["'JetBrains Mono'", 'monospace'],
+      },
+      colors: {
+        ink:    { DEFAULT: '#1a1a2e', 50: '#f0f0f8', 100: '#e0e0f0' },
+        slate2: { DEFAULT: '#334155', light: '#f8fafc' },
+      },
+      animation: {
+        'fade-up':      'fadeUp .55s cubic-bezier(.22,1,.36,1) both',
+        'fade-down':    'fadeDown .55s cubic-bezier(.22,1,.36,1) both',
+        'fade-in':      'fadeIn .4s ease both',
+        'slide-left':   'slideLeft .55s cubic-bezier(.22,1,.36,1) both',
+        'slide-right':  'slideRight .55s cubic-bezier(.22,1,.36,1) both',
+        'shimmer':      'shimmer 1.7s infinite',
+        'pulse-ring':   'pulseRing 2s ease-in-out infinite',
+        'float':        'float 6s ease-in-out infinite',
+        'gradient-x':   'gradientX 5s ease infinite',
+      },
+      keyframes: {
+        fadeUp:     { from: { opacity: 0, transform: 'translateY(20px)' }, to: { opacity: 1, transform: 'none' } },
+        fadeDown:   { from: { opacity: 0, transform: 'translateY(-16px)' }, to: { opacity: 1, transform: 'none' } },
+        fadeIn:     { from: { opacity: 0 }, to: { opacity: 1 } },
+        slideLeft:  { from: { opacity: 0, transform: 'translateX(-28px)' }, to: { opacity: 1, transform: 'none' } },
+        slideRight: { from: { opacity: 0, transform: 'translateX(28px)' }, to: { opacity: 1, transform: 'none' } },
+        shimmer:    { '0%': { backgroundPosition: '200% 0' }, '100%': { backgroundPosition: '-200% 0' } },
+        pulseRing:  { '0%,100%': { boxShadow: '0 0 0 0 var(--ring-color)' }, '50%': { boxShadow: '0 0 0 8px transparent' } },
+        float:      { '0%,100%': { transform: 'translateY(0)' }, '50%': { transform: 'translateY(-12px)' } },
+        gradientX:  { '0%,100%': { backgroundPosition: '0% 50%' }, '50%': { backgroundPosition: '100% 50%' } },
+      },
+      transitionTimingFunction: {
+        spring: 'cubic-bezier(.34,1.56,.64,1)',
+        smooth: 'cubic-bezier(.22,1,.36,1)',
+      },
+    },
+  },
+  plugins: [],
+}

frontend/vite.config.js

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+    proxy: {
+      '/api': { target: 'http://localhost:8000', changeOrigin: true },
+    },
+  },
+})

package-lock.json

@@ -0,0 +1,61 @@
+{
+  "name": "writeright",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "dependencies": {
+        "@tanstack/react-query": "^5.95.2",
+        "use-debounce": "^10.1.1"
+      }
+    },
+    "node_modules/@tanstack/query-core": {
+      "version": "5.95.2",
+      "resolved": "https://registry.npmjs.org/@tanstack/query-core/-/query-core-5.95.2.tgz",
+      "integrity": "sha512-o4T8vZHZET4Bib3jZ/tCW9/7080urD4c+0/AUaYVpIqOsr7y0reBc1oX3ttNaSW5mYyvZHctiQ/UOP2PfdmFEQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      }
+    },
+    "node_modules/@tanstack/react-query": {
+      "version": "5.95.2",
+      "resolved": "https://registry.npmjs.org/@tanstack/react-query/-/react-query-5.95.2.tgz",
+      "integrity": "sha512-/wGkvLj/st5Ud1Q76KF1uFxScV7WeqN1slQx5280ycwAyYkIPGaRZAEgHxe3bjirSd5Zpwkj6zNcR4cqYni/ZA==",
+      "license": "MIT",
+      "dependencies": {
+        "@tanstack/query-core": "5.95.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      },
+      "peerDependencies": {
+        "react": "^18 || ^19"
+      }
+    },
+    "node_modules/react": {
+      "version": "19.2.4",
+      "resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz",
+      "integrity": "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==",
+      "license": "MIT",
+      "peer": true,
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/use-debounce": {
+      "version": "10.1.1",
+      "resolved": "https://registry.npmjs.org/use-debounce/-/use-debounce-10.1.1.tgz",
+      "integrity": "sha512-kvds8BHR2k28cFsxW8k3nc/tRga2rs1RHYCqmmGqb90MEeE++oALwzh2COiuBLO1/QXiOuShXoSN2ZpWnMmvuQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 16.0.0"
+      },
+      "peerDependencies": {
+        "react": "*"
+      }
+    }
+  }
+}

package.json

@@ -0,0 +1,6 @@
+{
+  "dependencies": {
+    "@tanstack/react-query": "^5.95.2",
+    "use-debounce": "^10.1.1"
+  }
+}