# Todo Task Demo — Generated Backend

## Overview

**Todo Task Demo** is a FastAPI-based backend for a simple form submission application. Users can submit their name and email through a form, and all submissions are displayed in a list ordered by newest first.

This generated backend provides two REST API endpoints:
- **POST /submissions** — Create a new submission with name and email
- **GET /submissions** — Retrieve all submissions in reverse chronological order

The application is designed as a minimal demo with no authentication required and all data stored in memory (non-persistent).

## Requirements

- **Python 3.8+**
- **uv** (Python package installer and runner)

## Install uv

Install `uv` using the official installation script:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

After installation, restart your shell or source your shell configuration to make `uv` available in your PATH.

## Install Dependencies

The project uses `uv` to manage dependencies. All required packages (FastAPI, Uvicorn, Pydantic, etc.) are specified in the project configuration.

To install dependencies, simply run:

```bash
uv sync
```

This will create a virtual environment and install all necessary packages.

## Run the Backend

Start the FastAPI development server with hot-reload enabled:

```bash
uv run uvicorn main:app --reload
```

The backend will start on `http://localhost:8000` by default.

You should see output similar to:
```
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process
INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.
```

## API Docs

FastAPI automatically generates interactive API documentation:

- **Swagger UI**: [http://localhost:8000/docs](http://localhost:8000/docs)
- **ReDoc**: [http://localhost:8000/redoc](http://localhost:8000/redoc)

Use these interfaces to explore and test the API endpoints directly from your browser.

## OpenAPI JSON

The OpenAPI schema is available at:

- [http://localhost:8000/openapi.json](http://localhost:8000/openapi.json)

This JSON schema can be imported into API clients like Postman, Insomnia, or used to generate client SDKs.

## Project Files

```
.
├── main.py                 # FastAPI application entry point
├── pyproject.toml          # Project configuration and dependencies
└── README.md               # This file
```

**Key Components:**
- `main.py` contains all routes, models, validation logic, and in-memory storage
- Pydantic models enforce validation rules for name and email fields
- CORS middleware is enabled for frontend integration

## Example Workflow

### Create a Submission

Submit a new form entry with name and email:

```bash
curl -X POST http://localhost:8000/submissions \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Johnson",
    "email": "alice.johnson@example.com"
  }'
```

**Response:**
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Alice Johnson",
  "email": "alice.johnson@example.com",
  "created_at": "2024-01-15T10:30:00.123456",
  "updated_at": "2024-01-15T10:30:00.123456"
}
```

### Retrieve All Submissions

Get all submissions ordered by newest first:

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

**Response:**
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Alice Johnson",
    "email": "alice.johnson@example.com",
    "created_at": "2024-01-15T10:30:00.123456",
    "updated_at": "2024-01-15T10:30:00.123456"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Bob Smith",
    "email": "bob.smith@example.com",
    "created_at": "2024-01-15T10:25:00.123456",
    "updated_at": "2024-01-15T10:25:00.123456"
  }
]
```

### Validation Examples

The API enforces strict validation rules:

**Invalid email format:**
```bash
curl -X POST http://localhost:8000/submissions \
  -H "Content-Type: application/json" \
  -d '{"name": "Test User", "email": "invalid-email"}'
```

**Empty name:**
```bash
curl -X POST http://localhost:8000/submissions \
  -H "Content-Type: application/json" \
  -d '{"name": "   ", "email": "test@example.com"}'
```

Both will return validation error responses with detailed error messages.

## Next Steps

This generated backend is a starting point for development. Consider these improvements for a production-ready application:

1. **Database Persistence**: Replace in-memory storage with a proper database (PostgreSQL, MySQL, SQLite) using SQLAlchemy or an async ORM
2. **Authentication**: Add user authentication and authorization if submissions need to be protected or associated with user accounts
3. **Code Organization**: Split the monolithic `main.py` into separate modules:
   - `routers/` for API endpoint definitions
   - `services/` for business logic
   - `models/` for Pydantic schemas
   - `database/` for ORM models and database configuration
4. **Tests**: Add comprehensive test coverage using pytest and httpx:
   - Unit tests for validation logic
   - Integration tests for API endpoints
   - Test fixtures for database setup
5. **Pagination**: Implement pagination for the GET /submissions endpoint to handle large datasets efficiently
6. **Advanced Features**: 
   - Search and filter capabilities
   - Edit and delete operations
   - Email verification
   - Data export functionality
   - Rate limiting and security hardening