todoapp-vgv7cg/README.md

# Simple Todo API

A simple todo application built with FastAPI and SQLite.

## Features

- Create, read, update, and delete todos
- Category management system for organizing todos
- Priority levels for todos (low, medium, high)
- Due date functionality with timezone support
- Comprehensive filtering by category, priority, completion status, due dates, and overdue status
- Search functionality across title and description
- Specialized endpoints for overdue, due soon, and due today todos
- Sorting by due date or creation date
- Subtask management with hierarchical organization
- SQLite database with SQLAlchemy ORM
- Database migrations with Alembic
- FastAPI with automatic OpenAPI documentation
- CORS enabled for all origins
- Health check endpoint

## API Endpoints

### General
- `GET /` - Root endpoint with basic information
- `GET /health` - Health check endpoint
- `GET /docs` - Interactive API documentation (Swagger UI)
- `GET /redoc` - Alternative API documentation

### Todos
- `GET /api/v1/todos` - Get all todos (with comprehensive filtering and sorting)
- `POST /api/v1/todos` - Create a new todo
- `GET /api/v1/todos/{todo_id}` - Get a specific todo
- `PUT /api/v1/todos/{todo_id}` - Update a specific todo
- `DELETE /api/v1/todos/{todo_id}` - Delete a specific todo

### Due Date Endpoints
- `GET /api/v1/todos/overdue` - Get all overdue todos
- `GET /api/v1/todos/due-soon` - Get todos due within next N days (default 7)
- `GET /api/v1/todos/due-today` - Get todos due today

### Subtasks
- `POST /api/v1/todos/{todo_id}/subtasks` - Create a subtask for a specific todo
- `GET /api/v1/todos/{todo_id}/subtasks` - Get all subtasks for a specific todo
- `PUT /api/v1/todos/subtasks/{subtask_id}/move` - Move a subtask to different parent or make it a main todo

### Categories
- `GET /api/v1/categories` - Get all categories
- `POST /api/v1/categories` - Create a new category
- `GET /api/v1/categories/{category_id}` - Get a specific category
- `PUT /api/v1/categories/{category_id}` - Update a specific category
- `DELETE /api/v1/categories/{category_id}` - Delete a specific category

## Installation

1. Install the dependencies:
```bash
pip install -r requirements.txt
```

2. Run database migrations:
```bash
alembic upgrade head
```

3. Start the application:
```bash
uvicorn main:app --reload
```

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

## Project Structure

```
├── app/
│   ├── api/
│   │   └── v1/
│   │       ├── __init__.py
│   │       ├── todos.py
│   │       ├── categories.py
│   │       └── projects.py
│   ├── crud/
│   │   ├── __init__.py
│   │   ├── todo.py
│   │   ├── category.py
│   │   └── project.py
│   ├── db/
│   │   ├── __init__.py
│   │   ├── base.py
│   │   └── session.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── todo.py
│   │   ├── category.py
│   │   ├── project.py
│   │   └── tag.py
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── todo.py
│   │   ├── category.py
│   │   └── project.py
│   ├── utils/
│   │   ├── __init__.py
│   │   └── date_utils.py
│   └── __init__.py
├── alembic/
│   ├── versions/
│   │   ├── 001_initial_todo_table.py
│   │   ├── 002_add_priority_field.py
│   │   ├── 003_add_categories.py
│   │   ├── 004_add_projects.py
│   │   ├── 005_add_tags.py
│   │   ├── 006_add_subtasks.py
│   │   └── 007_add_due_date.py
│   ├── env.py
│   └── script.py.mako
├── alembic.ini
├── main.py
├── requirements.txt
└── README.md
```

## Database

The application uses SQLite database stored at `/app/storage/db/db.sqlite`. The database schema is managed using Alembic migrations.

## Models

### Todo Model
Each todo has the following fields:
- `id`: Unique identifier (auto-generated)
- `title`: Todo title (required, max 200 characters)
- `description`: Todo description (optional, max 500 characters)
- `completed`: Completion status (boolean, default: false)
- `priority`: Priority level (low, medium, high, default: medium)
- `category_id`: Reference to category (optional)
- `project_id`: Reference to project (optional)
- `due_date`: Due date and time with timezone (optional)
- `parent_id`: Reference to parent todo for subtasks (optional)
- `created_at`: Creation timestamp
- `updated_at`: Last update timestamp

#### Due Date Features
- `is_overdue`: Computed property indicating if todo is past due date
- `days_until_due`: Computed property showing days until due (negative if overdue)
- `is_due_soon`: Computed property indicating if todo is due within next 7 days
- `is_due_today`: Computed property indicating if todo is due today

#### Timezone Support
All due dates are stored with timezone information (UTC). The API accepts ISO 8601 formatted datetime strings and automatically handles timezone conversion.

### Category Model
Each category has the following fields:
- `id`: Unique identifier (auto-generated)
- `name`: Category name (required, max 100 characters, unique)
- `description`: Category description (optional, max 500 characters)
- `color`: Color code in hex format (optional, e.g., #FF0000)
- `created_at`: Creation timestamp
- `updated_at`: Last update timestamp

## Usage Examples

### Creating a Category
```bash
curl -X POST "http://localhost:8000/api/v1/categories" \
     -H "Content-Type: application/json" \
     -d '{"name": "Work", "description": "Work related tasks", "color": "#FF6B6B"}'
```

### Creating a Todo with a Category
```bash
curl -X POST "http://localhost:8000/api/v1/todos" \
     -H "Content-Type: application/json" \
     -d '{"title": "Review presentation", "description": "Review the quarterly presentation", "category_id": 1, "priority": "high"}'
```

### Creating a Todo with Due Date
```bash
curl -X POST "http://localhost:8000/api/v1/todos" \
     -H "Content-Type: application/json" \
     -d '{"title": "Submit report", "description": "Submit quarterly report", "due_date": "2024-12-31T23:59:59Z", "priority": "high"}'
```

### Filtering Todos by Category
```bash
curl "http://localhost:8000/api/v1/todos?category_id=1"
```

### Filtering Todos by Priority and Completion Status
```bash
curl "http://localhost:8000/api/v1/todos?priority=high&completed=false"
```

### Search Todos
```bash
curl "http://localhost:8000/api/v1/todos?search=presentation"
```

## Due Date Features

### Query Parameters for /api/v1/todos
- `overdue`: Filter overdue todos (`true`/`false`)
- `due_soon`: Filter todos due within next 7 days (`true`/`false`)
- `due_date_from`: Filter todos due after this date (ISO format)
- `due_date_to`: Filter todos due before this date (ISO format)
- `sort_by`: Sort by `due_date` or `created_at`

### Get Overdue Todos
```bash
curl "http://localhost:8000/api/v1/todos/overdue"
```

### Get Todos Due Soon (next 7 days)
```bash
curl "http://localhost:8000/api/v1/todos/due-soon"
```

### Get Todos Due Today
```bash
curl "http://localhost:8000/api/v1/todos/due-today"
```

### Filter by Date Range
```bash
curl "http://localhost:8000/api/v1/todos?due_date_from=2024-01-01T00:00:00Z&due_date_to=2024-12-31T23:59:59Z"
```

### Sort by Due Date
```bash
curl "http://localhost:8000/api/v1/todos?sort_by=due_date"
```

### Complex Filtering Example
```bash
curl "http://localhost:8000/api/v1/todos?priority=high&overdue=true&sort_by=due_date&page=1&per_page=20"
```