todoapp-zj3gfs/README.md

# FastAPI Todo Application

A modern, fast, and feature-rich todo management API built with FastAPI, SQLAlchemy, and SQLite.

## 🚀 Quick Start

### Prerequisites
- Python 3.8+
- pip package manager

### Installation & Setup

1. **Clone and navigate to the project:**
   ```bash
   git clone <repository-url>
   cd todoapp
   ```

2. **Create a virtual environment (recommended):**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

4. **Initialize the database:**
   ```bash
   alembic upgrade head
   ```

5. **Start the server:**
   ```bash
   uvicorn main:app --host 0.0.0.0 --port 8000
   ```

The API will be available at `http://localhost:8000`

## 📋 Features

- ✅ **Full CRUD Operations** - Create, read, update, and delete todos
- 🔍 **Pagination Support** - Efficient handling of large todo lists
- 📊 **SQLite Database** - Lightweight, serverless database
- 🔄 **Database Migrations** - Version-controlled schema changes with Alembic
- 📚 **Auto-generated Documentation** - Interactive API docs with Swagger UI
- 🌐 **CORS Enabled** - Cross-origin requests supported
- 💪 **Type Safety** - Full Pydantic validation and type hints
- 🏥 **Health Monitoring** - Built-in health check endpoint
- 🎯 **Production Ready** - Structured codebase with best practices

## 🛠 Tech Stack

- **FastAPI** - Modern, fast web framework for building APIs
- **SQLAlchemy** - SQL toolkit and ORM
- **Alembic** - Database migration tool
- **Pydantic** - Data validation using Python type annotations
- **SQLite** - Lightweight, file-based database
- **Uvicorn** - Lightning-fast ASGI server

## 📡 API Reference

### Base Endpoints
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/` | API information and links |
| GET | `/health` | Health check status |
| GET | `/docs` | Interactive API documentation |
| GET | `/redoc` | Alternative API documentation |
| GET | `/openapi.json` | OpenAPI specification |

### Todo Management
| Method | Endpoint | Description | Request Body |
|--------|----------|-------------|--------------|
| POST | `/todos/` | Create a new todo | `TodoCreate` |
| GET | `/todos/` | List all todos | Query params: `skip`, `limit` |
| GET | `/todos/{todo_id}` | Get specific todo | - |
| PUT | `/todos/{todo_id}` | Update todo | `TodoUpdate` |
| DELETE | `/todos/{todo_id}` | Delete todo | - |

### Request/Response Models

#### TodoCreate
```json
{
  "title": "string",
  "description": "string (optional)",
  "completed": false
}
```

#### TodoUpdate
```json
{
  "title": "string (optional)",
  "description": "string (optional)",
  "completed": "boolean (optional)"
}
```

#### TodoResponse
```json
{
  "id": 1,
  "title": "string",
  "description": "string",
  "completed": false,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

## 🗂 Project Structure

```
todoapp/
├── main.py                 # FastAPI application entry point
├── requirements.txt        # Python dependencies
├── alembic.ini            # Alembic configuration
├── ruff.toml              # Code linting configuration
├── app/
│   ├── __init__.py
│   ├── db/
│   │   ├── __init__.py
│   │   ├── base.py        # SQLAlchemy Base class
│   │   └── session.py     # Database session configuration
│   ├── models/
│   │   ├── __init__.py
│   │   └── todo.py        # Todo SQLAlchemy model
│   └── schemas/
│       ├── __init__.py
│       └── todo.py        # Pydantic schemas
└── alembic/
    ├── env.py             # Alembic environment configuration
    ├── script.py.mako     # Migration script template
    └── versions/          # Database migration files
        └── 001_initial_todo_table.py
```

## 🧪 Development

### Running in Development Mode
```bash
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

### Code Quality
This project uses Ruff for linting and formatting:
```bash
ruff check .
ruff format .
```

### Database Operations

**Create a new migration:**
```bash
alembic revision --autogenerate -m "Description of changes"
```

**Apply migrations:**
```bash
alembic upgrade head
```

**Rollback migrations:**
```bash
alembic downgrade -1
```

## 🔧 Configuration

### Database
- **Type:** SQLite
- **Location:** `/app/storage/db/db.sqlite`
- **Connection:** Automatically created on startup

### Environment Variables
No environment variables are required for basic operation. The application uses sensible defaults for development.

## 🏥 Health Check

The application includes a health check endpoint that returns the service status:

```bash
curl http://localhost:8000/health
```

Response:
```json
{
  "status": "healthy",
  "service": "Todo API"
}
```

## 📖 API Documentation

Once the server is running, access the documentation at:

- **Swagger UI:** http://localhost:8000/docs
- **ReDoc:** http://localhost:8000/redoc
- **OpenAPI JSON:** http://localhost:8000/openapi.json

## 🚀 Deployment

For production deployment, consider:

1. **Use a production WSGI server:**
   ```bash
   pip install gunicorn
   gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker
   ```

2. **Set up proper logging and monitoring**
3. **Configure environment-specific settings**
4. **Use a more robust database (PostgreSQL, MySQL)**
5. **Set up SSL/TLS certificates**

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

## 📝 License

This project is open source and available under the MIT License.