# Todo Task Submission — Generated Backend

## Overview

This is a FastAPI backend for the **Todo Task Submission** system, a simple form submission application that captures name and email entries and displays them in a list. The system provides RESTful APIs to create and retrieve submission records, with PostgreSQL database persistence.

The backend implements strict validation rules:
- Name must be 2-100 characters
- Email must be valid format with @ symbol and domain (max 255 characters)
- Both fields are required for submission

All submissions are immutable once created (no edit or delete functionality).

## Requirements

- Python 3.11+
- PostgreSQL 14+
- `uv` package manager

## Install uv

Install `uv`, the fast Python package manager:

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

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

## Install Dependencies

The project uses `uv` for dependency management. Install all required packages:

```bash
uv sync
```

This will install FastAPI, Uvicorn, SQLAlchemy, Pydantic, and other dependencies defined in `pyproject.toml`.

## Run the Backend

Start the development server with auto-reload enabled:

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

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

For production deployment, remove the `--reload` flag and configure appropriate host/port settings:

```bash
uv run uvicorn main:app --host 0.0.0.0 --port 8000
```

## API Docs

Once the server is running, interactive API documentation is available at:

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

These interfaces provide detailed endpoint documentation, request/response schemas, and allow you to test the APIs directly from your browser.

## OpenAPI JSON

The OpenAPI specification in JSON format is accessible at:

```
http://localhost:8000/openapi.json
```

This can be used to generate client SDKs or import into API testing tools like Postman or Insomnia.

## Project Files

```
.
├── main.py                 # FastAPI application entry point
├── models.py              # SQLAlchemy database models
├── schemas.py             # Pydantic request/response schemas
├── database.py            # Database configuration and session management
├── pyproject.toml         # Project dependencies and metadata
└── README.md              # This file
```

## Example Workflow

### Create a New Submission

Submit a new name and email entry:

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

Response:
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "John Doe",
  "email": "john.doe@example.com",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
```

### List All Submissions

Retrieve all submissions (ordered by newest first):

```bash
curl -X GET http://localhost:8000/submissions
```

Response:
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Jane Smith",
    "email": "jane.smith@example.com",
    "created_at": "2024-01-15T09:15:00Z",
    "updated_at": "2024-01-15T09:15:00Z"
  }
]
```

### Validation Example

Attempting to submit with invalid data (name too short):

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

Will return a 422 Unprocessable Entity error with validation details.

## Next Steps

This generated backend provides a solid foundation. Consider these enhancements for production readiness:

1. **Database Persistence**: Configure PostgreSQL connection string in environment variables and run migrations using the provided DDL schema (see `schema.sql` or migration scripts).

2. **Authentication**: Add JWT-based authentication or OAuth2 to protect endpoints and track submission ownership by user.

3. **Code Organization**: Refactor into separate modules:
   - `routers/` - API route handlers
   - `services/` - Business logic layer
   - `models/` - Database models
   - `schemas/` - Pydantic schemas
   - `repositories/` - Data access layer

4. **Testing**: Implement comprehensive test coverage:
   - Unit tests for validation logic
   - Integration tests for API endpoints
   - Database tests with fixtures

5. **Additional Features**:
   - Pagination for large submission lists
   - Search and filter by email
   - Rate limiting to prevent spam
   - Edit/delete functionality if business requirements change
   - Email verification workflow

6. **Production Configuration**:
   - Environment-based configuration
   - Logging and monitoring
   - CORS settings for frontend integration
   - Database connection pooling
   - Error handling and custom exception handlers