# 📝 Todo Management System - Full Stack Application
> A complete Todo management system with Flask REST API backend and Flutter mobile frontend
[](https://python.org)
[](https://flutter.dev)
[](https://flask.palletsprojects.com)
[](LICENSE)
## 🌟 Overview
This project is a full-stack Todo management application consisting of:
- **Backend**: Flask REST API with SQLite database and web interface
- **Frontend**: Flutter mobile application with modern UI
Perfect for learning full-stack development, API integration, and mobile app development.
## 📱 Screenshots
### Flutter Mobile App
<div align="center">
<img src="screenshots/flutter-home.png" width="250" alt="Flutter Home">
<img src="screenshots/flutter-add.png" width="250" alt="Add Todo">
<img src="screenshots/flutter-edit.png" width="250" alt="Edit Todo">
</div>
### Flask Web Interface
<div align="center">
<img src="screenshots/web-dashboard.png" width="600" alt="Web Dashboard">
</div>
## 🏗️ Project Structure
```
todo-management-system/
├── apiservice/ # Flask Backend
│ ├── app.py # Main Flask application
│ ├── models.py # Database models
│ ├── web_routes.py # Web interface routes
│ ├── api_routes.py # REST API routes
│ ├── templates.py # HTML templates
│ ├── requirements.txt # Python dependencies
│ └── todos.db # SQLite database (auto-created)
├── todolist/ # Flutter Frontend
│ ├── lib/
│ │ ├── main.dart # Main Flutter app
│ │ ├── models/ # Data models
│ │ ├── services/ # API services
│ │ └── widgets/ # UI components
│ ├── pubspec.yaml # Flutter dependencies
│ ├── android/ # Android configuration
│ └── ios/ # iOS configuration
├── screenshots/ # App screenshots
├── docs/ # Additional documentation
└── README.md # This file
```
## ✨ Features
### 🔥 Core Features
- ✅ **Create, Read, Update, Delete (CRUD)** todos
- ✅ **Mark todos as complete/incomplete**
- ✅ **Real-time synchronization** between web and mobile
- ✅ **Statistics dashboard** with progress tracking
- ✅ **Bulk operations** (delete all completed)
- ✅ **Search and filter** functionality
- ✅ **Responsive design** for all screen sizes
### 🌐 Backend (Flask)
- ✅ **REST API** with JSON responses
- ✅ **Web Interface** for management
- ✅ **SQLite Database** with SQLAlchemy ORM
- ✅ **CORS Support** for mobile app integration
- ✅ **Error Handling** and validation
- ✅ **API Documentation** page
- ✅ **Flash Messages** for user feedback
### 📱 Frontend (Flutter)
- ✅ **Material Design 3** UI
- ✅ **State Management** with Provider/setState
- ✅ **HTTP API Integration**
- ✅ **Offline Support** with local caching
- ✅ **Pull-to-refresh** functionality
- ✅ **Loading states** and error handling
- ✅ **Form validation**
- ✅ **Smooth animations**
## 🚀 Quick Start
### Prerequisites
- Python 3.8+
- Flutter 3.0+
- Git
### 1. Clone the Repository
```bash
git clone https://github.com/yourusername/todo-management-system.git
cd todo-management-system
```
### 2. Setup Backend (Flask)
```bash
cd apiservice
# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Run the Flask server
python app.py
```
The backend will be available at:
- **Web Interface**: http://localhost:5000
- **API Documentation**: http://localhost:5000/api-docs
- **API Base URL**: http://localhost:5000/api
### 3. Setup Frontend (Flutter)
```bash
cd ../todolist
# Get Flutter dependencies
flutter pub get
# Run the Flutter app
flutter run
```
## 📖 Detailed Setup Guide
### Backend Setup (Flask)
#### Environment Setup
```bash
cd apiservice
# Create and activate virtual environment
python -m venv todo_env
source todo_env/bin/activate # Linux/Mac
# OR
todo_env\Scripts\activate # Windows
```
#### Install Dependencies
```bash
pip install -r requirements.txt
```
#### Run Development Server
```bash
python app.py
```
#### Configuration
The Flask app uses these default settings:
- **Host**: `0.0.0.0` (accessible from mobile device)
- **Port**: `5000`
- **Database**: SQLite (`todos.db`)
- **Debug Mode**: `True` (disable in production)
### Frontend Setup (Flutter)
#### Install Flutter Dependencies
```bash
cd todolist
flutter pub get
```
#### Configure API URL
Edit `lib/services/api_service.dart`:
```dart
class ApiService {
// For Android Emulator
static const String baseUrl = 'http://10.0.2.2:5000/api';
// For iOS Simulator
// static const String baseUrl = 'http://localhost:5000/api';
// For Physical Device (replace with your computer's IP)
// static const String baseUrl = 'http://192.168.1.100:5000/api';
}
```
#### Platform-Specific Configuration
##### Android
Add to `android/app/src/main/AndroidManifest.xml`:
```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<application
android:usesCleartextTraffic="true"
...>
```
##### iOS
Add to `ios/Runner/Info.plist`:
```xml
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
```
#### Run the App
```bash
# List available devices
flutter devices
# Run on specific device
flutter run -d <device-id>
# Run in debug mode
flutter run --debug
# Run in release mode
flutter run --release
```
## 🔗 API Documentation
### Base URL
```
http://localhost:5000/api
```
### Authentication
Currently no authentication required (add JWT for production)
### Response Format
```json
{
"success": true,
"data": {...},
"message": "Operation successful"
}
```
### Endpoints
#### 📋 Todo Management
| Method | Endpoint | Description | Body |
|--------|----------|-------------|------|
| `GET` | `/todos` | Get all todos | - |
| `GET` | `/todos/{id}` | Get todo by ID | - |
| `POST` | `/todos` | Create new todo | `{"title": "string", "description": "string"}` |
| `PUT` | `/todos/{id}` | Update todo | `{"title": "string", "description": "string", "is_completed": boolean}` |
| `PATCH` | `/todos/{id}/toggle` | Toggle completion status | - |
| `DELETE` | `/todos/{id}` | Delete todo | - |
#### 📊 Statistics
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/todos/stats` | Get todo statistics |
| `DELETE` | `/todos/completed` | Delete all completed todos |
### Example API Calls
#### Create a new todo
```bash
curl -X POST http://localhost:5000/api/todos \
-H "Content-Type: application/json" \
-d '{
"title": "Learn Flutter",
"description": "Complete Flutter tutorial and build an app"
}'
```
#### Get all todos
```bash
curl http://localhost:5000/api/todos
```
#### Toggle todo completion
```bash
curl -X PATCH http://localhost:5000/api/todos/1/toggle
```
## 🏃♂️ Development Guide
### Backend Development
#### Adding New API Endpoints
1. Add route function in `api_routes.py`
2. Register route in `register_api_routes()`
3. Update API documentation
#### Database Schema Changes
1. Modify models in `models.py`
2. Delete `todos.db` file
3. Restart server to recreate database
#### Adding Web Interface Features
1. Add routes in `web_routes.py`
2. Update templates in `templates.py`
3. Add JavaScript if needed
### Frontend Development
#### Adding New Screens
1. Create new widget in `lib/screens/`
2. Add routing in `main.dart`
3. Update navigation
#### API Integration
1. Add service method in `lib/services/api_service.dart`
2. Handle loading and error states
3. Update UI components
#### State Management
Currently using `setState()` - consider upgrading to:
- Provider
- Riverpod
- Bloc
## 🧪 Testing
### Backend Testing
```bash
cd apiservice
# Install test dependencies
pip install pytest pytest-cov
# Run tests
python -m pytest tests/
# Run with coverage
python -m pytest --cov=. tests/
```
### Frontend Testing
```bash
cd todolist
# Run unit tests
flutter test
# Run integration tests
flutter test integration_test/
# Run tests with coverage
flutter test --coverage
```
### API Testing
Use the provided Python script:
```bash
cd apiservice
python test_api.py
```
Or use Postman/Insomnia with the collection in `docs/api-collection.json`
## 📦 Deployment
### Backend Deployment
#### Docker Deployment
```bash
cd apiservice
# Build image
docker build -t todo-api .
# Run container
docker run -p 5000:5000 todo-api
```
#### Traditional Deployment
1. Use production WSGI server (Gunicorn)
2. Set up reverse proxy (Nginx)
3. Use production database (PostgreSQL)
4. Configure environment variables
```bash
# Install Gunicorn
pip install gunicorn
# Run with Gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 app:app
```
### Frontend Deployment
#### Android APK
```bash
cd todolist
flutter build apk --release
```
#### iOS App
```bash
cd todolist
flutter build ios --release
```
#### Web Build
```bash
cd todolist
flutter build web
```
## 🔧 Configuration
### Environment Variables
#### Backend (`apiservice/.env`)
```env
FLASK_ENV=production
SECRET_KEY=your-secret-key-here
DATABASE_URL=sqlite:///todos.db
CORS_ORIGINS=*
DEBUG=False
```
#### Frontend
Configure in `lib/config/app_config.dart`:
```dart
class AppConfig {
static const String apiBaseUrl = 'https://your-api-domain.com/api';
static const bool enableLogging = false;
static const int requestTimeout = 30;
}
```
## 🐛 Troubleshooting
### Common Issues
#### Backend Issues
**Port already in use**
```bash
# Find process using port 5000
lsof -i :5000
# Kill process
kill -9 <PID>
```
**Database locked**
```bash
# Delete database file and restart
rm todos.db
python app.py
```
**CORS errors**
- Ensure Flask-CORS is installed
- Check CORS configuration in `app.py`
#### Frontend Issues
**Connection refused**
- Check API URL configuration
- Ensure backend is running
- Verify network permissions
**Build errors**
```bash
# Clean and rebuild
flutter clean
flutter pub get
flutter run
```
**Android network security**
- Add network security config
- Enable clear text traffic
### Performance Tips
#### Backend
- Use database connection pooling
- Implement caching (Redis)
- Add request rate limiting
- Optimize database queries
#### Frontend
- Implement pagination for large lists
- Use image caching
- Optimize build size
- Add loading placeholders
## 🤝 Contributing
We welcome contributions! Please follow these guidelines:
### Development Workflow
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Code Style
#### Backend (Python)
- Follow PEP 8
- Use Black formatter
- Add type hints
- Write docstrings
#### Frontend (Dart)
- Follow Dart style guide
- Use dartfmt
- Write widget tests
- Document public APIs
### Testing Requirements
- Add tests for new features
- Ensure all tests pass
- Maintain code coverage above 80%
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
```
MIT License
Copyright (c) 2025 Todo Management System
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```
## 🙏 Acknowledgments
- [Flask](https://flask.palletsprojects.com/) - Web framework
- [Flutter](https://flutter.dev/) - Mobile framework
- [Bootstrap](https://getbootstrap.com/) - CSS framework
- [Font Awesome](https://fontawesome.com/) - Icons
- [SQLAlchemy](https://www.sqlalchemy.org/) - Database ORM
## 📞 Support
If you have any questions or need help:
- 📧 Email: your-email@example.com
- 🐛 Issues: [GitHub Issues](https://github.com/yourusername/todo-management-system/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/yourusername/todo-management-system/discussions)
- 📚 Wiki: [Project Wiki](https://github.com/yourusername/todo-management-system/wiki)
## 🗺️ Roadmap
### Version 2.0 (Planned)
- [ ] User authentication and authorization
- [ ] Multi-user support with user isolation
- [ ] Categories and tags for todos
- [ ] Due dates and reminders
- [ ] File attachments
- [ ] Advanced search and filtering
- [ ] Dark mode support
- [ ] Offline sync capabilities
- [ ] Push notifications
- [ ] Export/import functionality
### Version 3.0 (Future)
- [ ] Team collaboration features
- [ ] Real-time updates with WebSockets
- [ ] Third-party integrations (Google Calendar, Slack)
- [ ] Advanced analytics and reporting
- [ ] Mobile widgets
- [ ] Voice input support
- [ ] AI-powered task suggestions
---
<div align="center">
**⭐ Star this repository if you found it helpful!**
Made with ❤️ by [Your Name](https://github.com/yourusername)
[🔝 Back to top](#-todo-management-system---full-stack-application)
</div>