Chronos Todo

Evolution of Todo — Hackathon II

A full-stack todo application demonstrating Spec-Driven Development across 5 evolutionary phases, from a simple console app to an AI-powered chatbot with natural language task management, deployed with Kubernetes on Oracle Cloud.

🚀 Live Demo

Frontend: https://chronos.ahsandev.site

Project Phases

✨ Phase III: Meet Chronos — Your AI Time Guardian

"Named after Chronos, the Greek personification of time — I am the guardian of your productivity and the keeper of your schedule."

Phase III introduces Chronos, an intelligent AI assistant that transforms task management through natural conversation. Built with the OpenAI Agents SDK and Model Context Protocol (MCP), Chronos represents the cutting edge of agentic AI technology.

🤖 Who is Chronos?

Chronos is not just another chatbot — it's a multi-agent system with a distinct personality and specialized capabilities:

🌟 Chronos's Capabilities

┌─────────────────────────────────────────────────────────────────┐
│                    CHRONOS AI ASSISTANT                          │
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐ │
│  │   TodoAgent  │  │ PlanningAgent│  │     QueryAgent         │ │
│  │   (Chronos)  │◄─┤   (Specialist)│   │    (Specialist)       │ │
│  │              │  │  - Weekly    │  │  - Semantic Search     │ │
│  │  - Main      │  │    Planning  │  │  - Complex Filters     │ │
│  │    Interface │  │  - Priority  │  │  - Task Discovery      │ │
│  │  - Handoffs  │  │    Mgmt     │  │                        │ │
│  └──────────────┘  └──────────────┘  └────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    MCP TOOLS (7 Tools)                          │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │
│  │ add_task │ │list_tasks│ │complete  │ │delete_task│           │
│  └──────────┘ └──────────┘ │_task     │ └──────────┘           │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐                         │
│  │update_task│ │ get_task │ │semantic  │                         │
│  │          │ │          │ │_search   │                         │
│  └──────────┘ └──────────┘ └──────────┘                         │
└─────────────────────────────────────────────────────────────────┘

🎙️ Voice Input & Transcription

Chronos understands spoken commands through Whisper API integration:

• 30-second recording limit — Quick voice memos
• Urdu biasing — Prevents Devanagari output for Urdu speakers
• Ambiguity confirmation — Asks for clarification when transcription is unclear
• Multi-language support — English, Urdu script (اردو), and Roman Urdu

🔍 Semantic Search (Vector Embeddings)

Unlike traditional keyword search, Chronos uses Qdrant vector database with OpenAI embeddings:

• Search by meaning: "grocery items" finds tasks with "buy milk", "eggs", "bread"
• Topic discovery: "work tasks" finds all professional-related items
• User-scoped: No cross-user data leakage
• Circuit breaker: Falls back to keyword search if Qdrant unavailable

🌐 Bilingual English/Urdu Support

Chronos is truly bilingual:

Phase IV & V: Kubernetes Deployment

Cloud Infrastructure

Deployment Artifacts

helm/chronos-todo/          # Helm chart
├── Chart.yaml
├── values.yaml             # Configuration (excluded from git - contains secrets)
├── templates/
│   ├── backend-deployment.yaml
│   ├── frontend-deployment.yaml
│   ├── redpanda-deployment.yaml
│   ├── dapr-pubsub.yaml
│   └── secret.yaml
scripts/
├── deploy-minikube.sh       # Local K8s deployment
└── deploy-oracle.sh         # Oracle OKE cloud deployment

Quick Deploy

Minikube (Local):

./scripts/deploy-minikube.sh

Oracle OKE (Production):

./scripts/deploy-oracle.sh

See DEPLOYMENT-GUIDE.md for full deployment instructions.

Quick Overview

evolution-of-todo/
├── src/                    # Phase I: Console App
├── backend/                # Phase II: FastAPI Backend
│   ├── app/
│   │   ├── ai/             # Phase III: OpenAI Agents + MCP
│   │   ├── dapr/           # Phase V: Dapr client
│   │   └── routes/         # API endpoints
│   └── Dockerfile         # Phase IV/V: Container image
├── frontend/               # Phase II: Next.js Frontend
│   ├── app/                # Next.js App Router
│   ├── components/         # React components
│   ├── lib/
│   │   ├── dapr/           # Phase V: Dapr client
│   │   └── api/            # API client
│   └── Dockerfile         # Phase IV/V: Container image
├── helm/                   # Phase IV/V: Kubernetes Helm charts
├── scripts/                # Deployment scripts
└── docs/phase4/, phase5/   # Deployment documentation

Tech Stack

Phase II (Full-Stack Web App)

Phase III (AI Chatbot) ⭐

Phase IV & V (Kubernetes) 🚀

Quick Start (Local Development)

Prerequisites

• Node.js 20+
• Python 3.13+
• Neon DB account (sign up free)
• UV package manager (recommended) or pip

1. Clone the Repository

git clone https://github.com/Ahsuu27488/evolution-of-todo.git
cd evolution-of-todo

2. Backend Setup

cd backend

# Create virtual environment
uv venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

# Install dependencies
uv pip install -r requirements.txt

# Create .env file
cp .env.example .env

Edit backend/.env:

# Database
DATABASE_URL=postgresql+asyncpg://user:pass@ep-xxxxx.region.aws.neon.tech/neondb?sslmode=require

# Authentication
BETTER_AUTH_SECRET=your-32-character-secret-here
CORS_ORIGINS=http://localhost:3000

# Phase III: AI Features
OPENAI_API_KEY=sk-your-openai-api-key
QDRANT_URL=https://your-cluster.qdrant.io
QDRANT_API_KEY=your-qdrant-api-key

# Feature Flags
PHASE_III_ENABLED=true

3. Frontend Setup

cd frontend

# Install dependencies
npm install

# Create .env.local file
cp .env.example .env.local

Edit frontend/.env.local:

# Database (shared with backend)
DATABASE_URL=postgresql+asyncpg://user:pass@ep-xxxxx.region.aws.neon.tech/neondb?sslmode=require

# Authentication (MUST match backend!)
BETTER_AUTH_SECRET=your-32-character-secret-here
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000

# API
NEXT_PUBLIC_API_URL=http://localhost:8000

# OpenAI (for chatbot)
OPENAI_API_KEY=sk-your-openai-api-key

⚠️ Important: BETTER_AUTH_SECRET must be identical in both backend/.env and frontend/.env.local!

4. Run Development Servers

Terminal 1 — Backend:

cd backend
source .venv/bin/activate
uvicorn app.main:app --reload --port 8000

Terminal 2 — Frontend:

cd frontend
npm run dev

5. Access the Application

Development

Spec-Driven Development

This project uses Spec-Driven Development with:

• Spec-Kit Plus for specification management
• Claude Code for AI-assisted development
• MCP Servers for context-aware tooling

Documentation Structure

• specs/ — Feature specifications (spec, plan, tasks)
• history/prompts/ — Prompt History Records (PHRs)
• history/adr/ — Architecture Decision Records
• .claude/skills/ — Reusable intelligence

License

MIT License — see LICENSE for details.

Built with Spec-Driven Development using Claude Code