Full-Stack AI-Powered Todo Application

A modern full-stack web application with Better Auth authentication, AI Chatbot powered by Groq (free!), and FastAPI backend.

🎯 Overview

This is a production-ready todo application featuring:

🤖 AI Chatbot: Manage tasks conversationally using Groq's Llama 3.3 70B (FREE!). Also Voice cmd feature enabled!
🔐 Better Auth + JWT: Secure authentication with token-based API access
✅ Task Management: Full CRUD operations with user isolation
🧠 MCP Server: Model Context Protocol for AI tool integration
👤 Multi-user Support: Each user has their own tasks
🎨 Modern UI: Responsive design with Tailwind CSS and dark mode
🗄️ PostgreSQL Database: Persistent data storage
🔒 Stateless Auth: Frontend and backend verify JWT tokens independently
🧪 Comprehensive Tests: 15/15 backend tests passing

🚀 Quick Start (5 Minutes)

1. Set Up Environment Variables

Create .env files with the SAME SECRET KEY in both:

backend/.env:

DATABASE_URL=postgresql://postgres:password@localhost:5432/todo_db
BETTER_AUTH_SECRET=your-secret-key-min-32-chars-long-change-in-production
GROQ_API_KEY=gsk_your_groq_api_key_here

frontend/.env.local:

NEXT_PUBLIC_API_URL=http://localhost:8000
BETTER_AUTH_SECRET=your-secret-key-min-32-chars-long-change-in-production
DATABASE_URL=postgresql://postgres:password@localhost:5432/todo_db

⚠️ CRITICAL:

The BETTER_AUTH_SECRET must be identical in both files!
Get your FREE Groq API key at https://console.groq.com (takes 2 minutes!)

2. Set Up Database

# Create PostgreSQL database
createdb todo_db

# Run migrations
cd backend
uv sync
uv run alembic upgrade head

cd ../frontend
npm install
npx better-auth migrate

3. Start Services

# Terminal 1 - Backend
cd backend
uv run uvicorn app.main:app --reload --port 8000

# Terminal 2 - Frontend  
cd frontend
npm run dev

4. Access the Application

Frontend: http://localhost:3000
Backend API: http://localhost:8000
API Docs: http://localhost:8000/docs
AI Chat: http://localhost:3000/chat (after login)

📖 Documentation

GROQ_SETUP.md - How to get your free Groq API key and setup
backend/README.md - Backend API documentation
frontend/README.md - Frontend documentation

🏗️ Architecture

How JWT Authentication Works

┌─────────────────────────────────────────────────────────────┐
│                    Frontend (Next.js)                       │
│  ┌──────────────┐      ┌──────────────┐                    │
│  │ Better Auth  │ ──▶  │   JWT Token  │                    │
│  │   Server     │      │  (7 days)    │                    │
│  └──────────────┘      └──────────────┘                    │
│                               │                             │
│                               ▼                             │
│                       Authorization: Bearer <token>         │
└───────────────────────────────┼─────────────────────────────┘
                                │
                   Shared Secret: BETTER_AUTH_SECRET
                                │
┌───────────────────────────────┼─────────────────────────────┐
│                               ▼                             │
│                       ┌──────────────┐                      │
│                       │  JWT Verify  │                      │
│                       │  Middleware  │                      │
│                       └──────────────┘                      │
│                               │                             │
│                               ▼                             │
│                       ┌──────────────┐                      │
│                       │  Task Routes │                      │
│                       │  (Filtered)  │                      │
│                       └──────────────┘                      │
│                    Backend (FastAPI)                        │
└─────────────────────────────────────────────────────────────┘

Flow:

User logs in → Better Auth issues JWT token (stored in HTTP-only cookie)
Frontend makes API call → Token attached to Authorization header
Backend verifies token → Uses shared secret to validate signature
Backend identifies user → Decodes user ID from token
Backend filters data → Returns only user's own tasks

📚 Tech Stack

Backend

Framework: FastAPI
AI Provider: Groq (Llama 3.3 70B) - FREE!
MCP Server: Model Context Protocol SDK
Database: PostgreSQL
ORM: SQLAlchemy 2.0
Migrations: Alembic
Authentication: JWT verification with python-jose
Password Hashing: Passlib + bcrypt
Testing: Pytest (15/15 passing ✅)

Frontend

Framework: Next.js 14 (App Router)
Language: TypeScript
Authentication: Better Auth with JWT plugin
Styling: Tailwind CSS
Theme: Dark/Light mode support
HTTP Client: Axios (auto-attaches JWT tokens)
Testing: Jest + React Testing Library

🔒 Security Features

Feature	Description
User Isolation	Each user only sees their own tasks
Stateless Auth	Backend doesn't need to call frontend to verify users
Token Expiry	JWT tokens expire after 7 days
Signature Verification	Tokens can't be forged without the secret key
Password Hashing	Better Auth handles secure bcrypt password storage
CORS Protection	Restricted to allowed origins

🧪 Testing

Backend Tests

cd backend
uv run pytest                    # Run all tests
uv run pytest --cov-report=html  # With coverage report

Results: ✅ 15/15 tests passing

Authentication: 8/8 tests
Task CRUD: 7/7 tests
User isolation verified
JWT verification working

Frontend Tests

cd frontend
npm test              # Run all tests
npm run test:watch    # Watch mode

🛠️ Development

Database Migrations

Backend (Alembic):

cd backend
uv run alembic revision --autogenerate -m "description"
uv run alembic upgrade head
uv run alembic downgrade -1

Frontend (Better Auth):

cd frontend
npx better-auth migrate

Code Quality

Backend:

cd backend
uv run black app tests      # Format
uv run flake8 app tests     # Lint
uv run mypy app             # Type check

Frontend:

cd frontend
npm run lint                # ESLint
npm run build               # Production build

📝 API Endpoints

Authentication

POST /api/auth/register - Register new user
POST /api/auth/login - Login and get JWT token
GET /api/auth/me - Get current user info

Tasks (JWT Required)

GET /api/{user_id}/tasks - List all tasks
POST /api/{user_id}/tasks - Create new task
GET /api/{user_id}/tasks/{task_id} - Get task by ID
PUT /api/{user_id}/tasks/{task_id} - Update task
DELETE /api/{user_id}/tasks/{task_id} - Delete task

AI Chat (JWT Required)

POST /api/chat - Send message to AI chatbot, get response
GET /api/chat - List user's conversations
GET /api/chat/{conversation_id} - Get conversation history

All endpoints require Authorization: Bearer <token> header and enforce user ownership.

🤖 AI Chatbot Features

The AI chatbot can help you manage tasks conversationally:

Example Commands:

"Create a task to buy groceries"
"Show me all my tasks"
"Mark task 5 as complete"
"Update task 3 description to 'Buy milk and eggs'"
"Delete the task about groceries"
"Show me only incomplete tasks"

MCP Tools Available:

create_task - Create new tasks
list_tasks - View all or filtered tasks
get_task - Get specific task details
update_task - Modify task properties
delete_task - Remove tasks
mark_task_complete / mark_task_incomplete - Toggle completion status

All AI operations are automatically scoped to the authenticated user!

🐛 Troubleshooting

401 Unauthorized Errors

✅ Verify BETTER_AUTH_SECRET matches in both .env files
✅ Check token is being sent in request headers (DevTools → Network)
✅ Try logout and login again to get fresh token

AI Chatbot Not Working

✅ Ensure GROQ_API_KEY is set in backend/.env
✅ Get your free key at https://console.groq.com
✅ Restart backend server after adding the key
✅ Check backend logs for any API errors

Database Connection Errors

✅ Ensure PostgreSQL is running: pg_isready
✅ Check DATABASE_URL in .env files
✅ Verify database exists: psql -l | grep todo_db

Better Auth Migration Fails

✅ Ensure DATABASE_URL is set in frontend/.env.local
✅ Check PostgreSQL permissions
✅ Try: cd frontend && npx better-auth migrate --force

CORS Errors

✅ Verify backend ALLOWED_ORIGINS includes frontend URL
✅ Check both services are running on correct ports
✅ Clear browser cache and cookies

📦 Project Structure

.
├── backend/                    # FastAPI backend
│   ├── app/
│   │   ├── models/            # SQLAlchemy models (User, Task, Conversation)
│   │   ├── schemas/           # Pydantic schemas  
│   │   ├── routers/           # API endpoints (auth, tasks, chat)
│   │   ├── services/          # JWT verification, AI agent
│   │   ├── mcp_server.py      # MCP server for AI tools
│   │   ├── config.py          # Settings (GROQ_API_KEY, BETTER_AUTH_SECRET)
│   │   └── main.py            # FastAPI app
│   ├── tests/                 # 15 tests (all passing)
│   └── alembic/               # Database migrations
│
├── frontend/                   # Next.js frontend
│   ├── app/                   
│   │   ├── (auth)/            # Login & register pages
│   │   ├── dashboard/         # Task management dashboard
│   │   └── chat/              # AI chatbot interface
│   ├── components/            # React components (Navigation, Tasks, Theme)
│   ├── contexts/              # Theme context for dark mode
│   ├── lib/
│   │   ├── auth-server.ts    # Better Auth config (JWT plugin)
│   │   ├── auth-client.ts    # Client-side auth helpers
│   │   └── api.ts            # Axios client (auto-attaches JWT)
│   └── hooks/                # Custom React hooks
│
├── GROQ_SETUP.md              # Free AI setup guide
└── README.md                  # This file

🚀 Deployment

Production Checklist

Generate secure BETTER_AUTH_SECRET (32+ chars): openssl rand -base64 32
Set environment variables in production
Ensure secrets match in frontend and backend
Set up HTTPS/SSL certificates
Update ALLOWED_ORIGINS with production domain
Set DEBUG=False in backend
Run database migrations
Test authentication flow end-to-end

Environment Variables for Production

Backend:

DATABASE_URL=postgresql://user:pass@host:5432/todo_db
BETTER_AUTH_SECRET=<your-production-secret>
GROQ_API_KEY=<your-groq-api-key>
ALLOWED_ORIGINS=https://yourdomain.com
DEBUG=False

Frontend:

NEXT_PUBLIC_API_URL=https://api.yourdomain.com
BETTER_AUTH_SECRET=<same-secret-as-backend>
DATABASE_URL=postgresql://user:pass@host:5432/todo_db

📄 License

This project is built following the Spec-Kit Plus methodology.

🤝 Contributing

Follow coding standards (backend: PEP 8, frontend: ESLint)
Write tests for new features
Update documentation as needed
Ensure all tests pass before committing

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
backend		backend
frontend		frontend
.gitignore		.gitignore
.python-version		.python-version
CLAUDE.md		CLAUDE.md
QUICK_START.md		QUICK_START.md
README.md		README.md
acli.exe		acli.exe
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation