Conversational Todo Manager

About This Demonstration

This repository is a demonstration of the Codev framework, a context-driven development methodology that enables systematic, AI-assisted software development. The project showcases two complete Codev protocol implementations:

1. SPIDER Protocol (demos 01-11): Comprehensive feature development with multi-agent consultation for the main application
2. TICK Protocol (demos 12-14): Rapid implementation for well-contained features (Railway deployment)

How This Was Built

Specification & Planning: Human-AI collaboration

• Human provided requirements, business logic, and pragmatic decisions
• Multiple AI agents (GPT-5, Gemini Pro) offered design perspectives
• Result: Comprehensive specification and phased implementation plan

Implementation: Fully autonomous AI execution

• All code written by AI following the approved plan
• 75 unit tests created to defend each phase
• Multiple I-D-E (Implement-Deploy-Evaluate) cycles for each plan phase
• No human code intervention - the human never directly looked at or edited code

Post-Implementation: Autonomous refinement

• Minor UX issues discovered through Playwright testing
• AI autonomously implemented fixes (streaming progress, model upgrade)
• Human continued to provide feedback without touching code

Key Insight: The human always had the option to review or edit code directly, but rich context made it unnecessary. This demonstrates Codev's core principle: context-driven development enables autonomous execution.

Explore the Complete Journey

📚 Read the Full Codev Tour - A comprehensive walkthrough of the entire development process across 14 git branches, showing both SPIDER and TICK protocols in action.

🔗 Visit the Codev Framework - Learn more about the methodology and protocols used to build this application.

---

The Application

A modern todo management application built with Next.js 15, featuring dual interfaces: a traditional GUI and a natural language conversational AI powered by Gemini 2.5 Pro.

---

Features

Dual Interface

• GUI Interface: Traditional todo list with inline editing, status updates, and quick add
• Conversational AI: Natural language todo management using Gemini 2.5 Flash
• Streaming Progress: Real-time progress updates during AI processing
• Seamless Integration: Both interfaces work with the same data in real-time

Todo Management

• ✅ Create, update, and delete todos
• ✅ Four status levels: Not Started, In Progress, Blocked, Done
• ✅ Optional due dates with smart formatting (Today, Tomorrow, specific dates)
• ✅ Intelligent sorting (overdue first, then by priority and date)
• ✅ Persistent storage with IndexedDB

AI Assistant Capabilities

• Natural language understanding: "Add a task to buy milk tomorrow"
• Query todos: "Show me my blocked tasks"
• Bulk operations: "Delete all completed todos"
• Status updates: "Mark the grocery task as done"
• Contextual awareness of current todos and dates

---

Getting Started

Prerequisites

• Node.js 18 or later
• npm or yarn
• Google Gemini API key (Get one here)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd codev-demo

2. Install dependencies:

   npm install

3. Configure environment variables: Create a .env.local file in the project root:

   GEMINI_API_KEY=your_api_key_here

4. Run the development server:

   npm run dev

5. Open your browser: Navigate to http://localhost:3000

---

Usage

GUI Interface

Add a Todo:

1. Type in the input field at the bottom of the todo list
2. Press Enter or click "Add"

Edit a Todo:

1. Click the pencil icon next to the todo title
2. Edit the title
3. Press Enter or click the checkmark

Change Status:

• Use the dropdown menu to change status (Not Started, In Progress, Blocked, Done)

Delete a Todo:

• Click the trash icon and confirm

Conversational AI Interface

Example Commands:

• "Add a task to buy groceries tomorrow"
• "Create a todo to finish the report, mark it in progress"
• "Show me all my blocked tasks"
• "Mark the grocery task as done"
• "Delete all completed todos"
• "What todos are due soon?"

Natural Language Support:

• Relative dates: "tomorrow", "next week", "in 3 days"
• Status vocabulary: "todo", "working on", "stuck", "completed"
• Bulk operations with confirmation

---

Technology Stack

Frontend

• Next.js 15: React framework with App Router
• TypeScript: Type-safe development
• Tailwind CSS: Utility-first styling
• shadcn/ui: Beautiful, accessible UI components
• Lucide React: Icon library

Storage

• IndexedDB: Browser-based persistent storage
• idb: Promise-based IndexedDB wrapper

AI Integration

• Google Gemini 2.5 Flash: Fast, efficient large language model
• Server-Sent Events (SSE): Streaming progress updates
• Function Calling: Structured AI responses
• MCP Server: Model Context Protocol for API key protection

Development & Testing

• Jest: Unit testing framework
• React Testing Library: Component testing
• fake-indexeddb: IndexedDB mocking for tests
• ESLint: Code linting
• Prettier: Code formatting (recommended)

---

Project Structure

codev-demo/
├── src/
│   ├── app/                      # Next.js app directory
│   │   ├── api/mcp/route.ts     # MCP server endpoint
│   │   ├── layout.tsx           # Root layout
│   │   ├── page.tsx             # Main page
│   │   └── globals.css          # Global styles
│   ├── components/              # React components
│   │   ├── ui/                  # shadcn/ui components
│   │   ├── AddTodoInput.tsx
│   │   ├── ChatInput.tsx
│   │   ├── ChatInterface.tsx
│   │   ├── ChatMessage.tsx
│   │   ├── StatusBadge.tsx
│   │   ├── TodoItem.tsx
│   │   └── TodoList.tsx
│   ├── hooks/                   # Custom React hooks
│   │   ├── useTodos.ts          # Todo management hook
│   │   └── useChat.ts           # Chat management hook
│   ├── lib/                     # Utility libraries
│   │   ├── actions/
│   │   │   └── executor.ts      # Action execution logic
│   │   ├── gemini/
│   │   │   ├── tools.ts         # Function declarations
│   │   │   ├── prompts.ts       # System prompt builder
│   │   │   └── parser.ts        # Response parser
│   │   ├── storage/
│   │   │   ├── db.ts            # IndexedDB setup
│   │   │   └── operations.ts    # CRUD operations
│   │   ├── date-utils.ts        # Date formatting utilities
│   │   ├── status-utils.ts      # Status utilities
│   │   └── todo-utils.ts        # Todo utilities
│   └── types/                   # TypeScript type definitions
│       ├── todo.ts              # Todo types
│       ├── actions.ts           # Action types
│       └── api.ts               # API types
├── codev/                       # SPIDER protocol documents
│   ├── specs/                   # Feature specifications
│   ├── plans/                   # Implementation plans
│   ├── reviews/                 # Code reviews
│   ├── resources/               # Architecture and API documentation
│   │   ├── arch.md              # Complete architecture documentation
│   │   └── API.md               # API endpoint documentation
│   └── protocols/               # Development protocols
├── .env.local                   # Environment variables (not committed)
├── package.json
└── README.md

---

Development

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests for specific file
npm test -- src/lib/todo-utils.test.ts

Building for Production

npm run build

Linting

npm run lint

---

Architecture

For comprehensive architecture documentation, see codev/resources/arch.md.

MCP Server Pattern

The application uses the Model Context Protocol (MCP) pattern to protect the Gemini API key:

1. Client sends natural language message
2. MCP Server (/api/mcp) adds context and calls Gemini
3. Gemini returns structured function calls
4. MCP Server transforms calls to actions
5. Client executes actions on local storage

Data Flow

User Input (GUI or Chat)
    ↓
useTodos Hook / useChat Hook
    ↓
Storage Operations / MCP Server
    ↓
IndexedDB / Gemini API
    ↓
State Update → UI Re-render

Storage Strategy

• Single-tab assumption: No multi-tab synchronization (per project requirements)
• IndexedDB for persistent browser storage
• Automatic sorting on load (overdue → due soon → blocked → in progress → not started → done)

---

Testing Strategy

Unit Tests (75 tests)

• Utilities: Date formatting, status normalization, todo sorting
• Storage: CRUD operations with fake-indexeddb
• Coverage: All business logic and data operations

Integration Testing

• Manual testing scenarios documented in implementation plan
• End-to-end testing with real browser (manual QA)

AI Testing Approach

• Production: Real Gemini API calls
• Development: Mock responses for deterministic testing
• Focus: Business logic testing, not AI behavior

---

Security Considerations

API Key Protection

• ✅ API key stored server-side only (.env.local)
• ✅ MCP server endpoint prevents client access
• ✅ API key never exposed to browser

Prompt Injection Protection

• ✅ User data wrapped in XML tags (<user_todos>)
• ✅ System prompt instructs model to treat tagged content as data only
• ✅ Function calling provides structured, validated outputs

---

Deployment

Railway Deployment

Railway is a modern cloud platform that makes it easy to deploy web applications with minimal configuration.

Prerequisites

1. Create a Railway account
2. Connect your GitHub account to Railway
3. Have your Gemini API key ready

Deploy to Railway

1. From Railway Dashboard:

   • Click "New Project"
   • Select "Deploy from GitHub repo"
   • Choose the ansari-project/codev-demo repository
   • Railway will automatically detect the Next.js app

2. Configure Environment Variables:

   • In your Railway project, go to the "Variables" tab
   • Add the following environment variable:

     GEMINI_API_KEY=your_gemini_api_key_here
     

   • Railway automatically provides the PORT variable

3. Deploy:

   • Railway will automatically build and deploy your app
   • The build command (npm run build) and start command (npm start) are auto-detected
   • Your app will be available at https://your-project.up.railway.app

4. Monitor Health:

   • Health check endpoint available at /api/health
   • Returns JSON with status and timestamp

Railway Configuration Notes

• Port Binding: The app automatically binds to Railway's PORT environment variable
• Build Command: npm run build (auto-detected)
• Start Command: npm start (configured to use $PORT)
• Node Version: 18+ (specified in package.json engines if needed)
• No Database Required: Uses client-side IndexedDB

Troubleshooting

• Build Failures: Check that all dependencies are in package.json
• Runtime Errors: Ensure GEMINI_API_KEY is set in Railway variables
• Port Issues: The app automatically uses Railway's PORT variable

---

Browser Compatibility

Supported Browsers:

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Requirements:

• IndexedDB support
• ES2020 features
• Fetch API

---

Contributing

This project was built using the SPIDER Protocol (Specification → Plan → Implementation → Documentation → Evaluation → Review). See the codev/ directory for development artifacts.

Development Workflow

1. Specification in codev/specs/
2. Implementation plan in codev/plans/
3. Code implementation with per-phase testing
4. Documentation (this README)
5. Multi-agent code review
6. Retrospective in codev/reviews/

---

License

[Specify your license here]

---

Acknowledgments

• Built with Next.js
• UI components by shadcn/ui
• AI powered by Google Gemini
• Developed using the SPIDER Protocol

---

Support

For issues, questions, or contributions, please refer to the project repository.