✍️ WriteWisely

AI-Powered Writing Coach — Learn, Practice, Write, and Grow.

A comprehensive writing improvement platform that combines structured learning paths, real-time grammar analysis, AI-powered chat coaching, project editing, and rich progress analytics — all gamified with credits, streaks, and badges.

✨ Features

📖 Learning Hub

A structured, level-based curriculum spanning 30 comprehensive levels across Beginner, Intermediate, and Advanced tiers. Each level includes:

Rich lesson content with examples and explanations
Interactive quizzes with instant scoring
Assignment submissions reviewed by AI
Progressive unlocking system

✏️ Practice Mode

Two powerful practice workflows:

Live Hint Mode — Real-time grammar and spelling suggestions as you type
Full Analysis Mode — Complete writing evaluation with scoring, corrections, and detailed feedback

📝 Project Editor

A full-featured document editor for longer writing pieces:

Create, save, and manage multiple writing projects
Live AI-powered grammar suggestions while editing
Document organization and version management

🤖 AI Chat Coach

An intelligent writing assistant that provides:

Context-aware guidance based on your writing progress
Document upload support (PDF/Text) for contextual analysis
Multi-conversation management with history
Cross-conversation reference capabilities

📊 Analytics Dashboard

A comprehensive 8-section analytics dashboard featuring:

Overview stats cards (level, credits, accuracy, streak, words, time)
Accuracy trend charts with 7-day visualization
This week's activity breakdown
Identified weak areas with practice recommendations
Achievement badges showcase
Exportable analytics data

🏆 Gamification System

Stay motivated with a rich reward system:

Credits — Earn credits for completing lessons, quizzes, and practice tasks
Streaks — Build daily streaks for consistent practice
10 Unique Badges — From "First Steps" to "Legend" status
Leaderboard Ranking — Track your position among other learners

🔐 Authentication & Security

Robust account management:

JWT-based authentication with bcrypt password hashing
OTP-based email verification via MailerSend
Password reset with OTP verification
Initial placement assessment to determine starting level

🔔 Notifications

Real-time notification system for:

Achievement unlocks and badge earnings
Streak milestones and reminders
Learning progress updates

🛠️ Tech Stack

Layer	Technologies
Frontend	React 18 · Vite 5 · Recharts · Lucide React · Font Awesome 7 · CSS3
Backend	FastAPI · Pydantic v2 · Motor (async MongoDB) · PyMongo
NLP / Grammar	spaCy (`en_core_web_sm`) · SymSpell · Custom rule engine
Database	MongoDB (local or Atlas)
Auth	JWT (python-jose) · bcrypt · OTP via MailerSend
AI / LLM	Google Gemini (primary) · OpenRouter (fallback) · Hugging Face (fallback)
File Processing	PyPDF for PDF parsing · Text file context extraction
Build Tools	Vite · npm · pip · Python venv

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        CLIENT (Browser)                         │
│                                                                 │
│   React 18 + Vite 5          Recharts         Lucide/FA Icons   │
│   ┌────────────────┐   ┌──────────────┐   ┌────────────────┐   │
│   │   App Shell    │   │  Analytics   │   │   Dashboard    │   │
│   │  Auth / Dash   │   │   Charts     │   │   Components   │   │
│   └───────┬────────┘   └──────────────┘   └────────────────┘   │
│           │  API calls via fetch()                              │
│           │  Vite proxy: /api → localhost:8000                  │
└───────────┼─────────────────────────────────────────────────────┘
            │
            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    SERVER (FastAPI + Uvicorn)                    │
│                                                                 │
│   ┌──────────────────────────────────────────────────────────┐  │
│   │                    Route Modules                         │  │
│   │  /api/auth    /api/learning   /api/practice              │  │
│   │  /api/project /api/chat       /api/checker               │  │
│   │  /api/analytics               /api/notifications         │  │
│   └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
│   │ Services │  │  Models  │  │ Prompts  │  │  Middleware   │  │
│   │ (LLM,   │  │(Pydantic)│  │  (LLM    │  │  (JWT Auth)  │  │
│   │ email)  │  │          │  │ templates│  │              │  │
│   └────┬─────┘  └──────────┘  └──────────┘  └──────────────┘  │
│        │                                                        │
│   ┌────┴─────────────────────────────────────────────────────┐  │
│   │            Local NLP Engine (pure Python)                │  │
│   │  spaCy (en_core_web_sm)  ·  SymSpell  ·  Grammar Rules  │  │
│   │  ~6ms avg latency  ·  No Java required                  │  │
│   └──────────────────────────────────────────────────────────┘  │
│                                                                 │
└────────┬────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐    ┌──────────────────────────┐
│         MongoDB                 │    │     External APIs        │
│                                 │    │                          │
│  Collections:                   │    │  • Google Gemini API     │
│  • users                        │    │  • OpenRouter API        │
│  • error_logs                   │    │  • Hugging Face API      │
│  • practice_submissions         │    │  • MailerSend (email)    │
│  • projects                     │    │                          │
│  • chat_conversations           │    └──────────────────────────┘
│  • analytics_snapshots          │
│  • notifications                │
└─────────────────────────────────┘

📁 Project Structure

WriteWisely/
├── 📄 README.md                    # This file
├── 📄 setup.bat                    # Windows setup script (one-click)
├── 📄 setup.sh                     # Linux/Mac setup script (one-click)
├── 📄 .gitignore
│
├── 📂 docs/
│   └── 📂 images/                  # README images and assets
│       ├── banner.png
│       ├── features.png
│       └── tech_stack.png
│
├── 📂 backend/
│   ├── 📄 main.py                  # FastAPI app entry point
│   ├── 📄 config.py                # DB connection, env loading, Mongo recovery
│   ├── 📄 requirements.txt         # Python dependencies
│   ├── 📄 .env                     # Environment variables (not committed)
│   │
│   ├── 📂 routes/                  # API route handlers
│   │   ├── auth.py                 # Signup, login, OTP, password reset
│   │   ├── learning.py             # Levels, lessons, quizzes, assignments
│   │   ├── practice.py             # Practice templates, check, submit
│   │   ├── project.py              # CRUD for writing projects
│   │   ├── chat.py                 # AI chat with document context
│   │   ├── checker.py              # Grammar/spell check endpoint
│   │   ├── analytics.py            # Dashboard stats, overview, export
│   │   └── notifications.py        # User notifications
│   │
│   ├── 📂 services/                # Business logic & external integrations
│   │   ├── checker_service.py      # Tiered spell/grammar pipeline
│   │   ├── local_grammar_engine.py # spaCy + SymSpell grammar engine
│   │   ├── spacy_grammar_rules.py  # Pure-Python grammar rule definitions
│   │   ├── llm_service.py          # Multi-provider LLM abstraction
│   │   ├── chat_mentor_service.py  # AI chat coach logic
│   │   ├── analytics_service.py    # Analytics computation
│   │   └── ...                     # Email, patterns, training data
│   ├── 📂 models/                  # Pydantic request/response models
│   ├── 📂 middleware/              # JWT auth middleware
│   ├── 📂 prompts/                 # LLM prompt templates
│   │
│   ├── 📂 data/                    # Static content (JSON-driven)
│   │   ├── 📂 lessons/             # Level 1-30 lesson content
│   │   ├── 📂 quizzes/             # Level 1-30 quiz questions
│   │   ├── practice_templates.json # 14 practice task templates
│   │   └── assessment_questions.json # Placement assessment
│   │
│   ├── 📄 seed_demo_account.py     # Seed a full demo account with data
│   ├── 📄 backfill_analytics.py    # Backfill analytics from history
│   ├── 📄 test_backend_full.py     # Comprehensive backend integration tests
│   └── 📄 _chat_e2e_stdlib.py      # Chat flow smoke test
│
└── 📂 frontend/
    ├── 📄 package.json             # Node dependencies & scripts
    ├── 📄 vite.config.js           # Vite config with API proxy
    ├── 📄 index.html               # HTML entry point
    │
    └── 📂 src/
        ├── 📄 App.jsx              # Root — auth vs authenticated routing
        ├── 📄 Auth.jsx             # Login/signup/OTP/reset flow
        │
        ├── 📂 pages/               # Full-page view components
        │   ├── Dashboard.jsx       # Main dashboard with stats & activity
        │   ├── LearningHome.jsx    # Learning levels overview
        │   ├── Lesson.jsx          # Individual lesson view
        │   ├── PracticeHome.jsx    # Practice template browser
        │   ├── PracticeEditor.jsx  # Practice writing interface
        │   ├── Projects.jsx        # Project list & editor
        │   ├── Analytics.jsx       # 8-section analytics dashboard
        │   ├── Assessment.jsx      # Placement assessment
        │   ├── Settings.jsx        # User settings
        │   └── ...                 # Auth-related pages
        │
        ├── 📂 components/          # Reusable UI components
        ├── 📂 services/            # API client & auth service
        ├── 📂 hooks/               # Custom React hooks
        ├── 📂 context/             # Theme & app context
        └── 📂 utils/               # Utility functions

🚀 Quick Start

Prerequisites

Requirement	Minimum Version	Download
Python	3.10+	python.org
Node.js	18+	nodejs.org
npm	9+	Comes with Node.js
MongoDB	6.0+	mongodb.com or use Atlas

Option 1: One-Click Setup (Recommended) ⚡

The fastest way to get started. The setup script handles everything automatically.

Windows:

git clone https://github.com/mujju-212/WriteWisely.git
cd WriteWisely
setup.bat

Linux / macOS:

git clone https://github.com/mujju-212/WriteWisely.git
cd WriteWisely
chmod +x setup.sh
./setup.sh

The setup script will:

✅ Verify Python, Node.js, and npm are installed
✅ Create a Python virtual environment
✅ Install all backend dependencies
✅ Download the spaCy English language model (en_core_web_sm)
✅ Generate a .env template (if not exists)
✅ Install all frontend dependencies

Option 2: Manual Setup

Step 1 — Clone the Repository

git clone https://github.com/mujju-212/WriteWisely.git
cd WriteWisely

Step 2 — Backend Setup

cd backend

# Create and activate virtual environment
python -m venv venv

# Windows
venv\Scripts\activate

# Linux/macOS
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Download the spaCy English language model
python -m spacy download en_core_web_sm

Step 3 — Configure Environment

# Copy the template (or create your own)
cp .env.example .env    # Linux/macOS
copy .env.example .env  # Windows

# Edit .env and add your API keys

⚠️ Important: You need at least one LLM API key (Gemini recommended) for AI features to work.

Step 4 — Frontend Setup

cd ../frontend
npm install

Step 5 — Start MongoDB

# If using local MongoDB, make sure the service is running:
# Windows: Start "MongoDB Server" from Services
# Linux: sudo systemctl start mongod
# macOS: brew services start mongodb-community

# Or set MONGODB_URL in .env to your Atlas connection string

Step 6 — Start the Application

Terminal 1 — Backend:

cd backend
venv\Scripts\activate        # Windows
# source venv/bin/activate   # Linux/macOS
uvicorn main:app --reload

Backend runs at → http://localhost:8000

Terminal 2 — Frontend:

cd frontend
npm run dev

Frontend runs at → http://localhost:5173

Vite is configured to proxy /api requests to http://localhost:8000 automatically.

Step 7 — (Optional) Seed Demo Data

cd backend
python seed_demo_account.py

This creates a demo account with pre-populated learning progress, practice history, and analytics data.

⚙️ Environment Configuration

Create a backend/.env file with the following configuration:

# ═══════════════════════════════════════════════════════
#  CORE CONFIGURATION
# ═══════════════════════════════════════════════════════

MONGODB_URL=mongodb://localhost:27017/writewisely
JWT_SECRET=change-this-to-a-strong-random-secret
JWT_ALGORITHM=HS256
JWT_EXPIRY_HOURS=24

# ═══════════════════════════════════════════════════════
#  LLM PROVIDERS  (configure at least one)
# ═══════════════════════════════════════════════════════

# Provider 1: Google Gemini (recommended — primary)
GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-2.0-flash

# Provider 2: OpenRouter (fallback)
OPENROUTER_API_KEY=your_openrouter_key_here
LLM_MODEL=google/gemma-3-12b-it:free

# Provider 3: Hugging Face (fallback)
HF_API_KEY=your_huggingface_key_here
HF_MODEL=meta-llama/Llama-3.2-1B-Instruct

# ═══════════════════════════════════════════════════════
#  EMAIL / OTP
# ═══════════════════════════════════════════════════════

MAILERSEND_API_KEY=your_mailersend_key
MAILERSEND_DOMAIN=your_domain.com
SENDER_EMAIL=noreply@your_domain.com
SENDER_NAME=WriteWisely
ALLOW_OTP_DEV_FALLBACK=true    # Set to true for dev (OTP logged to console)

# ═══════════════════════════════════════════════════════
#  LOCAL MONGO RECOVERY (dev convenience)
# ═══════════════════════════════════════════════════════

AUTO_START_LOCAL_MONGO=true
LOCAL_MONGO_DBPATH=              # Leave empty for auto-detection

Configuration Notes

Variable	Purpose
`MONGODB_URL`	MongoDB connection string. Supports local or Atlas.
`JWT_SECRET`	Must be changed for production. Used to sign auth tokens.
`GEMINI_API_KEY`	Primary LLM provider. Get a free key at aistudio.google.com
`ALLOW_OTP_DEV_FALLBACK`	When `true`, OTPs are logged to console instead of sent via email
`AUTO_START_LOCAL_MONGO`	Backend auto-starts local `mongod` if connection fails (dev only)

📡 API Reference

Base URL: http://localhost:8000/api

Interactive API docs (Swagger UI): http://localhost:8000/docs

🔐 Auth Endpoints — /api/auth

Method	Endpoint	Description
`POST`	`/signup`	Create a new account
`POST`	`/verify-otp`	Verify email with OTP
`POST`	`/resend-otp`	Resend verification OTP
`POST`	`/login`	Authenticate and receive JWT
`POST`	`/logout`	Invalidate session
`POST`	`/forgot-password`	Request password reset OTP
`POST`	`/verify-reset-otp`	Verify reset OTP
`POST`	`/reset-password`	Set new password
`GET`	`/profile`	Get user profile
`PUT`	`/profile`	Update user profile
`PUT`	`/change-password`	Change password
`GET`	`/assessment-questions`	Get placement assessment
`POST`	`/submit-assessment`	Submit assessment answers
`DELETE`	`/delete-account`	Delete user account

📖 Learning Endpoints — /api/learning

Method	Endpoint	Description
`GET`	`/levels`	List all levels with progress
`GET`	`/levels/{level_id}`	Get level details & lesson content
`POST`	`/lesson/{level_id}/complete`	Mark lesson as completed
`POST`	`/quiz/{level_id}`	Submit quiz answers
`POST`	`/assignment/{level_id}`	Submit assignment for AI review

✏️ Practice Endpoints — /api/practice

Method	Endpoint	Description
`GET`	`/templates`	List all practice templates
`GET`	`/templates/{task_id}`	Get specific template details
`POST`	`/check`	Live grammar/spelling check
`POST`	`/submit`	Submit practice for full analysis
`GET`	`/history`	Get practice submission history

📝 Project Endpoints — /api/project

Method	Endpoint	Description
`GET`	`/list`	List all user projects
`POST`	`/create`	Create a new project
`GET`	`/{project_id}`	Get project content
`PUT`	`/{project_id}`	Update project content
`DELETE`	`/{project_id}`	Delete a project

🤖 Chat Endpoints — /api/chat

Method	Endpoint	Description
`POST`	`/upload-document`	Upload document for context
`GET`	`/documents`	List uploaded documents
`DELETE`	`/documents/{document_id}`	Remove a document
`GET`	`/history`	Get chat conversation history
`POST`	`/send`	Send message to AI coach
`DELETE`	`/clear`	Clear chat history

🔍 Checker Endpoint — /api/checker

Method	Endpoint	Description
`POST`	`/check`	Check text for grammar & spelling errors

📊 Analytics Endpoints — /api/analytics

Method	Endpoint	Description
`GET`	`/dashboard`	Full dashboard data
`GET`	`/overview`	Summary overview stats
`PUT`	`/settings`	Update analytics preferences
`GET`	`/export`	Export analytics data

🔔 Notification Endpoints — /api/notifications

Method	Endpoint	Description
`GET`	`/`	Get all notifications
`PATCH`	`/mark-read`	Mark specific notifications as read
`PATCH`	`/mark-all-read`	Mark all as read

📚 Content & Data

All educational content is JSON-driven and located in backend/data/:

File / Directory	Content
`data/lessons/level_01.json` — `level_30.json`	Structured lesson content for all 30 levels
`data/quizzes/level_01.json` — `level_30.json`	10-question quizzes per level
`data/practice_templates.json`	14 structured practice templates with LLM evaluation criteria
`data/assessment_questions.json`	Placement test (10 questions) to determine starting level

Adding New Content

To extend the curriculum, simply add new JSON files following the existing format:

// Example: data/lessons/level_31.json
{
  "level_id": 31,
  "title": "Your New Lesson Title",
  "difficulty": "Advanced",
  "topic": "Writing",
  "sections": [
    {
      "heading": "Introduction",
      "content": "Lesson content here...",
      "examples": ["Example 1", "Example 2"]
    }
  ]
}

🔧 Developer Utilities

Seed Demo Account

Populates a demo account with full learning progress, practice history, error logs, and analytics:

cd backend
python seed_demo_account.py

Backfill Analytics

Generates analytics snapshots from existing historical data:

cd backend
python backfill_analytics.py

Chat Smoke Test

End-to-end test for the AI chat pipeline:

cd backend
python _chat_e2e_stdlib.py

Full Integration Tests

Comprehensive backend test suite covering all endpoints:

cd backend
python test_backend_full.py

🐛 Troubleshooting

🔴 401 Unauthorized on Login

Common causes:

Wrong email or password
Account exists but email not verified (email_verified=false)
Backend connected to a different MongoDB data directory

Quick check — verify users exist:

cd backend
python -c "from pymongo import MongoClient; db=MongoClient('mongodb://localhost:27017/writewisely').get_default_database(); print(f'Users: {db.users.count_documents({})}')"

🔴 MongoDB Connection Refused (WinError 10061)

Ensure MongoDB service is running:
- Windows: Open Services → Start "MongoDB Server"
- Linux: sudo systemctl start mongod
- macOS: brew services start mongodb-community
Verify MONGODB_URL in backend/.env
Enable AUTO_START_LOCAL_MONGO=true for automatic recovery in dev

🔴 503 Database Unavailable

MongoDB is unreachable or startup failed
Confirm port and connection string in .env
Check backend console for detailed connection error logs
Restart the backend after fixing MongoDB

🟡 AI Features Not Working

Ensure at least one LLM API key is set in backend/.env
Gemini is the primary provider — get a free key at aistudio.google.com
The system automatically falls back to OpenRouter → Hugging Face if the primary fails
Check backend console for LLM provider error messages

🟡 OTP Not Received

For development, set ALLOW_OTP_DEV_FALLBACK=true in .env
The OTP will be printed to the backend console
For production, configure MailerSend API keys properly

🔒 Security Notes

⚠️ Important for Production Deployment

🔑 Never commit real API keys or secrets — use .env files
🔄 Rotate keys immediately if they were accidentally exposed
🛡️ Use a strong, random JWT_SECRET (at least 32 characters)
🔐 Use production-grade MongoDB credentials with authentication enabled
🌐 Restrict CORS origins in main.py to your actual deployment domain
📧 Disable ALLOW_OTP_DEV_FALLBACK in production

👥 Contributors

_{Mujutaba M N}
_{🏆 Project Lead & Core Developer}

_Ashlesh
_{💻 Developer}

_{Nandeesh BM}
_{💻 Developer}

_{SK Darshan (SKDARSHAN22)}
_{💻 Developer}

📄 License

This project is currently unlicensed. If you intend reuse, please add a LICENSE file (e.g., MIT).

Made with ❤️ by the WriteWisely Team
Empowering better writing, one lesson at a time.

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 35 Commits
backend		backend
docs/images		docs/images
frontend		frontend
.gitignore		.gitignore
README.md		README.md
setup.bat		setup.bat
setup.sh		setup.sh

Folders and files

Latest commit

History

Repository files navigation

✍️ WriteWisely

📑 Table of Contents

✨ Features

📖 Learning Hub

✏️ Practice Mode

📝 Project Editor

🤖 AI Chat Coach

📊 Analytics Dashboard

🏆 Gamification System

🔐 Authentication & Security

🔔 Notifications

🛠️ Tech Stack

🏗️ Architecture

📁 Project Structure

🚀 Quick Start

Prerequisites

Option 1: One-Click Setup (Recommended) ⚡

Option 2: Manual Setup

Step 1 — Clone the Repository

Step 2 — Backend Setup

Step 3 — Configure Environment

Step 4 — Frontend Setup

Step 5 — Start MongoDB

Step 6 — Start the Application

Step 7 — (Optional) Seed Demo Data

⚙️ Environment Configuration

Configuration Notes

📡 API Reference

📚 Content & Data

Adding New Content

🔧 Developer Utilities

Seed Demo Account

Backfill Analytics

Chat Smoke Test

Full Integration Tests

🐛 Troubleshooting

🔒 Security Notes

👥 Contributors

📄 License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages