✅

README.md

@@ -1,31 +1,88 @@
-# Polly-API: FastAPI Poll Application
+# Polly API Documentation
 
-A simple poll application built with FastAPI, SQLite, and JWT authentication. Users can register, log in, create, retrieve, vote on, and delete polls. The project follows best practices with modular code in the `api/` directory.
+## Overview
+
+Polly API is a comprehensive polling application built with FastAPI, featuring user authentication, poll management, and a robust voting system. The application includes both a server API and a Python client library for easy integration.
 
 ## Features
 
-- User registration and login (JWT authentication)
-- Create, retrieve, and delete polls
-- Add options to polls (minimum of two options required)
-- Vote on polls (authenticated users only)
-- View poll results with vote counts
-- SQLite database with SQLAlchemy ORM
-- Modular code structure for maintainability
+### Authentication
+
+- **User Registration**: Create new user accounts
+
+  - Endpoint: `/register`
+  - Method: `POST`
+  - Secure password hashing using bcrypt
+
+- **User Login**: Authenticate users and receive JWT tokens
+  - Endpoint: `/login`
+  - Method: `POST`
+  - Returns JWT token for protected endpoints
+  - Token-based authentication using python-jose
+
+### Poll Management
+
+- **Create Polls**
+
+  - Endpoint: `/polls`
+  - Method: `POST`
+  - Protected endpoint (requires authentication)
+  - Support for multiple options
+
+- **List Polls**
+
+  - Endpoint: `/polls`
+  - Method: `GET`
+  - Pagination support with skip/limit parameters
+  - Public endpoint
+
+- **Get Single Poll**
+
+  - Endpoint: `/polls/{poll_id}`
+  - Method: `GET`
+  - Access detailed poll information
+
+- **Delete Polls**
+  - Endpoint: `/polls/{poll_id}`
+  - Method: `DELETE`
+  - Protected endpoint
+  - Only poll owner can delete
+
+### Voting System
+
+- **Cast Votes**
+
+  - Endpoint: `/polls/{poll_id}/vote`
+  - Method: `POST`
+  - Protected endpoint
+  - One vote per user per poll
+
+- **View Results**
+  - Endpoint: `/polls/{poll_id}/results`
+  - Method: `GET`
+  - Real-time vote counting
+  - Detailed results per option
 
 ## Project Structure
 
 ```
 Polly-API/
 ├── api/
 │   ├── __init__.py
-│   ├── auth.py
-│   ├── database.py
-│   ├── models.py
-│   ├── routes.py
-│   └── schemas.py
-├── main.py
-├── requirements.txt
-└── README.md
+│   ├── auth.py        # Authentication logic
+│   ├── database.py    # Database configuration
+│   ├── models.py      # SQLAlchemy models
+│   ├── routes.py      # API endpoints
+│   └── schemas.py     # Pydantic schemas
+├── client/
+│   ├── __init__.py
+│   ├── auth.py        # Authentication client
+│   └── polls.py       # Poll operations client
+├── tests/
+│   └── test_routes.py # Integration tests
+├── main.py           # Application entry point
+├── requirements.txt  # Project dependencies
+└── README.md        # Documentation
 ```
 
 ## Setup Instructions
@@ -37,23 +94,204 @@ git clone <your-repo-url>
 cd Polly-API
 ```
 
-2. **Set up a Python virtual environment (recommended)**
+2. **Set up a Python virtual environment**
 
-A virtual environment helps isolate your project dependencies.
+```bash
+python3 -m venv venv
+source venv/bin/activate  # On Unix/macOS
+```
 
-- **On Unix/macOS:**
+3. **Install dependencies**
 
-  ```bash
-  python3 -m venv venv
-  source venv/bin/activate
-  ```
+```bash
+pip install -r requirements.txt
+```
+
+## Technical Implementation
+
+### Database Structure
+
+- SQLite database using SQLAlchemy ORM
+- Tables:
+  - Users: Store user information
+  - Polls: Store poll questions and metadata
+  - Options: Store poll options
+  - Votes: Track user votes
+
+### Security Features
+
+- Password Hashing (bcrypt)
+- JWT Authentication
+- Protected Routes
+- Input Validation using Pydantic
+- Proper error handling
+
+### Client Library Usage
+
+#### Authentication
+
+```python
+from client.auth import register_user, login_user
+
+# Register new user
+user = register_user("username", "password")
+
+# Login and get token
+token = login_user("username", "password")
+```
+
+#### Poll Operations
+
+```python
+from client.polls import create_poll, vote_on_poll, get_polls
+
+# Create new poll
+poll = create_poll(
+    question="Your question?",
+    options=["Option 1", "Option 2"],
+    token=token
+)
+
+# Vote on poll
+vote_on_poll(poll.id, poll.options[0].id, token)
+
+# Get paginated polls
+polls = get_polls(skip=0, limit=10)
+```
+
+### Testing
+
+The project includes comprehensive integration tests:
+
+- Run all tests:
+
+```bash
+pytest tests/test_routes.py -v
+```
+
+- Run tests with coverage:
+
+```bash
+pytest tests/test_routes.py --cov=api --cov-report=term-missing -v
+```
+
+Test coverage includes:
+
+- User registration and authentication
+- Poll creation and management
+- Voting system
+- Error cases
+- Authorization checks
+
+## API Response Examples
+
+### User Registration Response
+
+```json
+{
+  "id": 1,
+  "username": "user123"
+}
+```
+
+### Login Response
+
+```json
+{
+  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
+  "token_type": "bearer"
+}
+```
+
+### Poll Creation Response
+
+```json
+{
+  "id": 1,
+  "question": "What's your favorite color?",
+  "created_at": "2025-09-12T10:00:00",
+  "owner_id": 1,
+  "options": [
+    {
+      "id": 1,
+      "text": "Blue",
+      "poll_id": 1
+    },
+    {
+      "id": 2,
+      "text": "Red",
+      "poll_id": 1
+    }
+  ]
+}
+```
+
+### Poll Results Response
+
+```json
+{
+  "poll_id": 1,
+  "question": "What's your favorite color?",
+  "results": [
+    {
+      "option_id": 1,
+      "text": "Blue",
+      "vote_count": 3
+    },
+    {
+      "option_id": 2,
+      "text": "Red",
+      "vote_count": 2
+    }
+  ]
+}
+```
+
+## Dependencies
+
+```
+fastapi
+uvicorn
+sqlalchemy
+pydantic
+passlib[bcrypt]
+python-jose[cryptography]
+python-dotenv
+requests
+pytest
+```
+
+## Error Handling
+
+The API implements proper error handling with appropriate HTTP status codes:
+
+- 200: Success
+- 201: Created
+- 400: Bad Request
+- 401: Unauthorized
+- 404: Not Found
+- 500: Server Error
+
+Custom exceptions are implemented for specific error cases with meaningful error messages.
+
+## Future Enhancements
+
+- Email verification
+- OAuth integration
+- Real-time updates using WebSockets
+- Poll categories and tags
+- Advanced analytics
+- Rate limiting
+- Cache implementation
+
+````
 
 - **On Windows (cmd):**
 
   ```cmd
   python -m venv venv
   venv\Scripts\activate
-  ```
+````
 
 - **On Windows (PowerShell):**