diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f1eb7ee
--- /dev/null
+++ b/README.md
@@ -0,0 +1,171 @@
+# TaskFlow - Personal Task Management Application
+
+A modern, mobile-first task management application built with React, TypeScript, and Express. TaskFlow helps you organize and track your tasks efficiently with multiple views including calendar scheduling, kanban boards, and project templates.
+
+## Features
+
+- 📱 **Mobile-First Design** - Fully responsive with touch-friendly interactions
+- 📅 **Calendar View** - Schedule tasks with drag-and-drop functionality
+- 📊 **Kanban Board** - Visualize workflow with traditional, weekly, and monthly views
+- ⏱️ **Time Tracking** - Built-in timer to track time spent on tasks
+- 🏷️ **Labels & Priorities** - Color-coded organization system
+- 📁 **Project Templates** - Reusable templates for common workflows
+- 🌓 **Dark Mode** - Automatic theme switching
+- 🐳 **Docker Ready** - Production-ready Docker deployment
+
+## Tech Stack
+
+- **Frontend**: React 18, TypeScript, Tailwind CSS, shadcn/ui
+- **Backend**: Express.js, Node.js
+- **Database**: PostgreSQL with Drizzle ORM
+- **State Management**: TanStack Query
+- **Build Tools**: Vite, ESBuild
+
+## Quick Start
+
+### Development (Local)
+
+1. **Install dependencies:**
+   ```bash
+   npm install
+   ```
+
+2. **Start development server:**
+   ```bash
+   npm run dev
+   ```
+
+3. **Open in browser:**
+   ```
+   http://localhost:5000
+   ```
+
+The development version uses in-memory storage by default.
+
+### Production (Docker)
+
+See [DEPLOYMENT.md](./DEPLOYMENT.md) for comprehensive Docker deployment instructions.
+
+**Quick Docker Start:**
+
+1. **Create `.env` file:**
+   ```bash
+   cp .env.example .env
+   ```
+
+2. **Start services:**
+   ```bash
+   docker-compose up -d
+   ```
+
+3. **Access application:**
+   ```
+   http://localhost:5000
+   ```
+
+## Project Structure
+
+```
+taskflow/
+├── client/                 # React frontend
+│   ├── src/
+│   │   ├── components/    # Reusable UI components
+│   │   ├── pages/         # Page components
+│   │   └── lib/           # Utilities and hooks
+│   └── index.html
+├── server/                 # Express backend
+│   ├── index.ts          # Server entry point
+│   ├── routes.ts         # API routes
+│   ├── storage.ts        # Storage implementations
+│   └── db.ts             # Database connection
+├── shared/                 # Shared types and schemas
+│   └── schema.ts         # Database schema & types
+├── Dockerfile             # Production Docker image
+├── docker-compose.yml     # Docker orchestration
+└── DEPLOYMENT.md          # Deployment guide
+```
+
+## Available Scripts
+
+- `npm run dev` - Start development server with hot reload
+- `npm run build` - Build for production
+- `npm start` - Start production server
+- `npm run check` - TypeScript type checking
+- `npm run db:push` - Push database schema changes
+
+## Environment Variables
+
+### Development
+```env
+NODE_ENV=development
+PORT=5000
+```
+
+### Production (Docker)
+```env
+NODE_ENV=production
+DATABASE_URL=postgresql://user:password@postgres:5432/taskflow
+PORT=5000
+```
+
+See `.env.example` for all available options.
+
+## Database
+
+TaskFlow uses PostgreSQL with Drizzle ORM for type-safe database operations.
+
+### Schema
+
+- **users** - User accounts (future multi-user support)
+- **labels** - Color-coded task labels
+- **tasks** - Task items with metadata
+
+### Switching to Database in Development
+
+To use the PostgreSQL database in development:
+
+1. Set environment variable:
+   ```bash
+   export USE_DB=true
+   ```
+
+2. Ensure `DATABASE_URL` is set in your environment
+
+3. Start the development server
+
+## API Endpoints
+
+### Labels
+- `GET /api/labels` - Get all labels
+- `GET /api/labels/:id` - Get specific label
+- `POST /api/labels` - Create new label
+- `PATCH /api/labels/:id` - Update label
+- `DELETE /api/labels/:id` - Delete label
+
+### Tasks
+- `GET /api/tasks` - Get all tasks
+- `GET /api/tasks/:id` - Get specific task
+- `POST /api/tasks` - Create new task
+- `PATCH /api/tasks/:id` - Update task
+- `DELETE /api/tasks/:id` - Delete task
+
+### Health
+- `GET /api/health` - Health check endpoint
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch
+3. Commit your changes
+4. Push to the branch
+5. Create a Pull Request
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Support
+
+For deployment help, see [DEPLOYMENT.md](./DEPLOYMENT.md)
+
+For issues and questions, please open an issue on the repository.
diff --git a/replit.md b/replit.md
index 8f62e09..e260795 100644
--- a/replit.md
+++ b/replit.md
@@ -60,6 +60,27 @@ Preferred communication style: Simple, everyday language.
 
 **Priority and Status Management**: Tasks support priority levels (low, medium, high) and status tracking (todo, in progress, done) with visual indicators.
 
+## Production Deployment
+
+**Docker Stack Support**: The application is production-ready with full Docker support for containerized deployment:
+- **Multi-stage Docker Build**: Optimized production image with separate build and runtime stages
+- **PostgreSQL Database**: Separate database container with persistent volume storage
+- **Health Monitoring**: Built-in health checks for both application and database services
+- **Environment Configuration**: Flexible configuration via environment variables
+- **Graceful Shutdown**: Proper cleanup and connection pool management
+- **Database Migrations**: Automatic schema creation and seeding on first startup
+
+**Storage Flexibility**: 
+- **Development**: Uses in-memory storage (MemStorage) for rapid prototyping
+- **Production**: Switches to PostgreSQL-backed storage (DbStorage) using Drizzle ORM
+- **Environment-driven**: Automatically selects storage based on NODE_ENV or USE_DB flag
+
+**Database Management**:
+- **Connection Pooling**: Uses node-postgres (pg) for efficient connection management
+- **Auto-migrations**: Enables pgcrypto extension and creates tables on startup
+- **Default Data**: Seeds default labels automatically on fresh database
+- **Graceful Cleanup**: Properly closes connections on shutdown signals
+
 ## External Dependencies
 
 ### UI and Styling