phase-3/README.md

Phase 3 - AI-Native Todo System

Status: Complete & Locked

Overview

Phase 3 transformed the Todo application into a conversational AI-native system where users manage tasks through natural language in English and Urdu.

Key Features

AI-Powered Chatbot

• ✅ Natural language task management (English & Urdu)
• ✅ Qwen LLM integration via Hugging Face SDK
• ✅ Model Context Protocol (MCP) tools for secure operations
• ✅ Context-aware conversations with memory persistence

Web Application

• ✅ Next.js frontend with modern UI
• ✅ FastAPI backend with REST API
• ✅ Better Auth authentication system
• ✅ Real-time chat interface

Security & Isolation

• ✅ JWT-based user authentication
• ✅ Multi-tenant data isolation (user_id filters)
• ✅ Stateless server architecture
• ✅ MCP tool security (no direct DB access)

Multi-Language Support

• ✅ English: Full grammar and command support
• ✅ Urdu: Complete input and response support
• ✅ Auto-detection and language matching

Structure

phase-3/
├── backend/               # FastAPI + MCP + Chatbot
│   ├── src/
│   │   ├── models/       # Todo, User, Conversation, Message
│   │   ├── services/     # Business logic, MCP tools
│   │   ├── api/          # REST endpoints (/api/chat)
│   │   └── main.py       # FastAPI application entry
│   ├── alembic/          # Database migrations
│   ├── requirements.txt  # Python dependencies
│   └── Dockerfile        # Container image (for Phase 4)
│
└── frontend/             # Next.js + Chat UI
    ├── src/
    │   ├── components/   # React components
    │   ├── pages/        # Next.js pages
    │   └── services/     # API client
    ├── package.json      # Node dependencies
    └── Dockerfile        # Container image (for Phase 4)

Tech Stack

Backend

• Framework: FastAPI (Python 3.11+)
• Database: Neon PostgreSQL (serverless)
• Auth: Better Auth (JWT)
• AI Engine: Qwen via Hugging Face Inference API
• MCP SDK: Official Model Context Protocol SDK
• Migrations: Alembic

Frontend

• Framework: Next.js 14 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• UI Components: Shadcn/ui
• Deployment: Vercel

Architecture

User → Frontend → Backend API → MCP Tools → Database
                  ↓
              Chatbot Service
                  ↓
              Qwen LLM (HuggingFace)
                  ↓
              MCP Tool Calls → CRUD Operations

Key Principles

1. AI-Native Interaction: Chatbot is primary interface, not add-on
2. Stateless Server: All conversation state in database
3. Persistence: Every interaction stored and replayable
4. Security: Absolute user isolation via user_id
5. MCP-First: All operations via standardized tools

Usage

Backend Setup

cd phase-3/backend
pip install -r requirements.txt
alembic upgrade head
cp .env.example .env  # Configure DATABASE_URL, JWT_SECRET, HF_API_KEY
uvicorn src.main:app --reload

Frontend Setup

cd phase-3/frontend
npm install
cp .env.example .env.local  # Configure NEXT_PUBLIC_API_URL
npm run dev

Chat with the AI

1. Open http://localhost:3000
2. Sign up / Log in
3. Click "Chat" tab
4. Type commands like:
   • "Add a task to buy groceries"
   • "میرے لیے خریداری کا کام شامل کریں"
   • "Show me my tasks"
   • "میرے کام دکھائیں"

Testing

# Backend tests
cd phase-3/backend
pytest tests/

# Frontend tests
cd phase-3/frontend
npm test

# E2E chat flow test
# 1. Login
# 2. Send chat message
# 3. Verify task created
# 4. Check language detection

Performance

• Chat latency: <10 seconds (p95)
• API response: <2 seconds (p95)
• Conversation load: <500ms (p95)

Evolution

Phase 3 code is LOCKED and serves as the foundation for Phase 4:

• Phase 4: Adds containerization, Kubernetes, and DevOps automation
• No business logic changes in Phase 4
• All Phase 3 features preserved identically

Deployment

Current deployment:

• Frontend: Vercel (production)
• Backend: Hugging Face Spaces (production)
• Database: Neon PostgreSQL (serverless)

See DEPLOYMENT.md in backend/ for full deployment guide.