# Todo Task Submission System — Generated Backend

## Overview

This is a FastAPI-based backend for a simple form submission system that allows anonymous users to submit their name and email, and view all submitted entries. The system provides two REST API endpoints for creating and retrieving submissions.

**Key Features:**
- Submit name and email through a POST endpoint
- Retrieve all submissions ordered by creation date (newest first)
- Automatic UUID generation for each submission
- Timestamp tracking (created_at, updated_at)
- Server-side validation for name and email fields
- No authentication required

**Technology Stack:**
- FastAPI (Python web framework)
- PostgreSQL (database)
- Pydantic (data validation)
- uvicorn (ASGI server)

## Requirements

- Python 3.8+
- PostgreSQL database
- 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 terminal or run:

```bash
source $HOME/.cargo/env
```

## Install Dependencies

The project uses `uv` for dependency management. Dependencies are automatically installed when you run the application, but you can also install them explicitly:

```bash
uv pip install fastapi uvicorn pydantic pydantic-settings sqlalchemy psycopg2-binary
```

## 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`

**Environment Variables:**

Set the following environment variable for database connection:

```bash
export DATABASE_URL="postgresql://user:password@localhost:5432/submissions_db"
```

Or create a `.env` file in the project root:

```
DATABASE_URL=postgresql://user:password@localhost:5432/submissions_db
```

## API Docs

Once the server is running, access the interactive API documentation:

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

These interfaces allow you to explore and test all available endpoints interactively.

## OpenAPI JSON

The OpenAPI specification is available at:

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

## Project Files

```
.
├── main.py                 # FastAPI application entry point
├── models.py              # SQLAlchemy database models
├── schemas.py             # Pydantic request/response schemas
├── database.py            # Database connection and session management
├── requirements.txt       # Python dependencies
├── .env                   # Environment variables (create this)
└── README.md             # This file
```

## Example Workflow

### Create a New Submission

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

**Expected Response:**

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

### Retrieve All Submissions

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

**Expected Response:**

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

### Validation Example

Attempting to submit invalid data:

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

Will return a 422 validation error with details about the validation failures.

## Next Steps

To evolve this backend into a production-ready application, consider the following improvements:

1. **Database Persistence**: Currently using in-memory or basic database setup. Implement proper database migrations using Alembic to manage schema changes over time.

2. **Authentication & Authorization**: Add user authentication (JWT tokens, OAuth2) to secure endpoints and track which user created each submission.

3. **Code Organization**: Split the monolithic `main.py` into separate modules:
   - `routers/` - API route handlers
   - `services/` - Business logic layer
   - `models/` - Database models
   - `schemas/` - Pydantic schemas
   - `core/` - Configuration and utilities

4. **Testing**: Implement comprehensive test coverage:
   - Unit tests for business logic
   - Integration tests for API endpoints
   - Database fixture management with pytest
   - Test coverage reporting

5. **Additional Features**:
   - Add pagination for the GET endpoint (limit/offset or cursor-based)
   - Implement rate limiting to prevent abuse
   - Add CORS middleware for frontend integration
   - Implement logging and monitoring
   - Add health check endpoints
   - Set up Docker containerization
   - Configure CI/CD pipelines

6. **Validation Enhancements**: Add more sophisticated validation rules and custom validators for edge cases.

7. **Documentation**: Expand API documentation with more examples, error codes, and usage guidelines.