Python gRPC Todo Application

A modern, full-featured todo application built with Python, gRPC, FastAPI, and SQLAlchemy. This project demonstrates best practices for building scalable microservices with gRPC and provides both CLI and web interfaces.

Features

• gRPC Backend: High-performance gRPC service with full CRUD operations
• Database Persistence: SQLite for development, PostgreSQL for production
• Multiple Interfaces: CLI client and web interface
• Task Management: Create, read, update, delete, complete, and archive tasks
• Advanced Filtering: Filter by status, priority, category, and search
• Rich CLI: Interactive command-line interface with beautiful output
• Modern Web UI: Responsive web interface with Bootstrap
• Type Safety: Full type hints and Pydantic models
• Error Handling: Comprehensive error handling and validation

Table of Contents

• Quick Start
• Installation
• Usage
• API Documentation
• Development
• Architecture
• Contributing

Quick Start

Prerequisites

• Python 3.8 or higher
• pip package manager

1. Clone and Setup

git clone <repository-url>
cd python-grpc-todo
pip install -r requirements.txt

2. Generate Protobuf Files

python -m grpc_tools.protoc --proto_path=. --python_out=. --grpc_python_out=. proto/todo.proto

3. Start the gRPC Server

python scripts/start_server.py

4. Use the CLI Client

# Interactive mode
python scripts/start_cli.py interactive

# Or use commands directly
python src/client/cli.py create "Buy groceries" --priority HIGH --category "Shopping"
python src/client/cli.py list

5. Start the Web Interface

python scripts/start_web.py

Visit http://localhost:8000 to use the web interface.

Installation

Development Dependencies

pip install -r requirements-dev.txt

Database Setup

The application uses SQLite by default. For production, configure PostgreSQL:

# Set environment variable
export DATABASE_URL="postgresql://user:password@localhost/todo_db"

Usage

CLI Client

The CLI client provides a rich command-line interface:

# Create a task
python src/client/cli.py create "Learn gRPC" --priority HIGH --category "Learning"

# List all tasks
python src/client/cli.py list

# List tasks with filters
python src/client/cli.py list --status TODO --priority HIGH

# Get task details
python src/client/cli.py get <task-id>

# Update a task
python src/client/cli.py update <task-id> --title "Updated title" --status IN_PROGRESS

# Complete a task
python src/client/cli.py complete <task-id>

# Archive a task
python src/client/cli.py archive <task-id>

# Delete a task
python src/client/cli.py delete <task-id>

# Interactive mode
python src/client/cli.py interactive

Web Interface

Start the web server:

python src/web/app.py

The web interface provides:

• Create, edit, and delete tasks
• Filter and search tasks
• Mark tasks as complete
• Archive tasks
• Responsive design for mobile and desktop

gRPC Server

Start the gRPC server:

python src/server/grpc_server.py

The server provides:

• Full CRUD operations for tasks
• Filtering and pagination
• Health check endpoint
• Error handling and validation

API Documentation

gRPC Service

The main service is TasksService with the following methods:

• CreateTask(CreateTaskRequest) -> Task
• GetTask(GetTaskRequest) -> Task
• ListTasks(ListTasksRequest) -> TaskList
• UpdateTask(UpdateTaskRequest) -> Task
• DeleteTask(DeleteTaskRequest) -> EmptyResponse
• CompleteTask(GetTaskRequest) -> Task
• ArchiveTask(GetTaskRequest) -> Task
• HealthCheck(HealthCheckRequest) -> HealthCheckResponse

REST API (Web Interface)

The web interface exposes REST endpoints:

• POST /api/tasks - Create task
• GET /api/tasks/{id} - Get task
• GET /api/tasks - List tasks
• PUT /api/tasks/{id} - Update task
• DELETE /api/tasks/{id} - Delete task
• POST /api/tasks/{id}/complete - Complete task
• POST /api/tasks/{id}/archive - Archive task
• GET /health - Health check

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   CLI Client    │    │   Web Client    │    │  Mobile Client  │
│   (Rich CLI)    │    │   (FastAPI)     │    │   (Future)      │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                       │
          └──────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────▼─────────────┐
                    │      gRPC Server          │
                    │   (TasksService)          │
                    └─────────────┬─────────────┘
                                  │
                    ┌─────────────▼─────────────┐
                    │    Business Logic        │
                    │   (TaskService)           │
                    └─────────────┬─────────────┘
                                  │
                    ┌─────────────▼─────────────┐
                    │    Database Layer         │
                    │   (SQLAlchemy)            │
                    └───────────────────────────┘

Components

1. gRPC Server (src/server/grpc_server.py)

   • Handles gRPC requests
   • Implements the TasksService
   • Error handling and validation

2. Business Logic (src/services/task_service.py)

   • Task management operations
   • Data validation
   • Business rules

3. Data Models (src/models/task.py)

   • SQLAlchemy models
   • Database operations
   • Repository pattern

4. CLI Client (src/client/cli.py)

   • Rich command-line interface
   • Interactive mode
   • Beautiful output formatting

5. Web Interface (src/web/app.py)

   • FastAPI web server
   • REST API endpoints
   • HTML/JavaScript frontend

Development

Project Structure

python-grpc-todo/
├── src/
│   ├── models/          # Database models
│   ├── services/        # Business logic
│   ├── server/         # gRPC server
│   ├── client/         # CLI client
│   ├── web/            # Web interface
│   └── utils/          # Utilities
├── proto/              # Protocol buffer definitions
├── config/             # Configuration
├── tests/              # Test files
├── scripts/            # Setup scripts
└── docs/               # Documentation

Running Tests

pytest

Code Quality

# Format code
black src/ tests/

# Type checking
mypy src/

# Linting
flake8 src/ tests/

# Sort imports
isort src/ tests/

Database Migrations

# Create migration
alembic revision --autogenerate -m "Description"

# Apply migrations
alembic upgrade head

Configuration

Environment Variables

• DATABASE_URL: Database connection string
• SERVER_HOST: Server host (default: 0.0.0.0)
• SERVER_PORT: Server port (default: 5000)
• LOG_LEVEL: Logging level (default: INFO)
• DEBUG: Debug mode (default: False)

Database Configuration

The application supports multiple databases:

• SQLite (default): sqlite:///./todo.db
• PostgreSQL: postgresql://user:password@localhost/todo_db

Deployment

Docker

# Build image
docker build -t python-grpc-todo .

# Run container
docker run -p 5000:5000 -p 8000:8000 python-grpc-todo

Production Considerations

1. Database: Use PostgreSQL for production
2. Security: Implement authentication and authorization
3. Monitoring: Add logging and metrics
4. Scaling: Use load balancers and multiple instances
5. SSL: Enable HTTPS/TLS for web interface

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run quality checks
6. Submit a pull request

Development Setup

# Clone repository
git clone <repository-url>
cd python-grpc-todo

# Install dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Start development server
python src/server/grpc_server.py

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• gRPC for the high-performance RPC framework
• FastAPI for the modern web framework
• SQLAlchemy for the ORM
• Rich for beautiful CLI output
• Bootstrap for the web interface

Support

For questions and support:

• Create an issue on GitHub
• Check the documentation
• Review the examples in the examples/ directory

---

Happy coding!