Spec driven development project created

DocumentationREADME.md

@@ -0,0 +1,231 @@
+# Book Review API
+
+A RESTful API for managing books and reviews with automatic rating aggregation and filtering capabilities.  
+Built using **Spec-Driven Development** with FastAPI.
+
+---
+
+## Overview
+
+This backend-only application provides a complete book review system with:
+
+- Create books with validation
+- Add reviews with automatic average rating calculation
+- Aggregate review statistics (average_rating, review_count)
+- Filter books by minimum rating
+- In-memory data persistence (no database required)
+- Comprehensive automated test coverage
+- Interactive API documentation
+
+The application runs fully locally and requires no external database setup.
+
+---
+
+# Spec-Driven Development
+
+All features were defined before implementation in the `SPECS/` directory.
+
+## Implemented Feature Specifications
+
+- 01-create-book.md
+- 02-add-review.md
+- 03-list-books.md
+- 04-filter-books.md
+- 05-get-book-by-id.md
+- 06-list-reviews.md
+- 07-testing-framework.md
+
+### Development Rules Followed
+
+- No feature implemented without a spec
+- Acceptance criteria documented and satisfied
+- Tests validate all acceptance criteria
+- TODO hygiene maintained
+- README is human-facing only
+
+---
+
+## Quick Start
+
+### Prerequisites
+- Python 3.8 or higher
+- pip (Python package installer)
+
+### Installation
+
+1. **Clone the repository** (if not already done):
+   ```bash
+   git clone <repository-url>
+   cd github-test
+   ```
+
+2. **Create a virtual environment** (recommended):
+   ```bash
+   python -m venv venv
+
+   # On Windows
+   venv\Scripts\activate
+
+   # On macOS/Linux
+   source venv/bin/activate
+   ```
+
+3. **Install dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+### Running the Application
+
+Start the API server:
+```bash
+uvicorn app.main:app --reload
+```
+
+The API will be available at `http://localhost:8000`
+
+**Interactive API Documentation:**
+- Swagger UI: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+
+### Running Tests
+
+Run all tests:
+```bash
+pytest
+```
+
+Run tests with coverage report:
+```bash
+pytest --cov=app --cov-report=html
+```
+
+Run tests with verbose output:
+```bash
+pytest -v
+```
+
+Run specific test file:
+```bash
+pytest tests/test_add_review.py
+pytest tests/test_create_book.py
+pytest tests/test_filter_books.py
+pytest tests/test_list_books.py
+```
+
+## API Endpoints
+
+### Health Check
+- `GET /` - Health check endpoint
+
+### Task Operations
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/books` | Create a new books |
+| GET | `/books` | Get all books (with optional filters) |
+| GET | `/books/{id}` | Get a specific book by ID |
+
+### Query Parameters
+
+`GET /books` supports the following query parameters:
+- min_rating must be between 0 and 5
+- Invalid values return 400 Bad Request
+
+**Examples:**
+# Get all books
+GET /books
+
+# Get books with rating >= 4
+GET /books?min_rating=4
+
+# Get books with rating >= 3.5
+GET /books?min_rating=3.5
+
+
+## 🧪 Testing
+
+The project includes comprehensive test coverage across two test files:
+
+**`tests/test_create_book.py`** -
+- Successful book creation
+- Required field validation
+- Empty field validation
+- Invalid year handling
+
+**`tests/test_add_review.py`** - 
+- Add single review
+- Add multiple reviews
+- Automatic average rating calculation
+- Review count update
+- Invalid rating handling (outside 1–5)
+
+**`tests/test_list_books.py`** - 
+- Empty book list
+- Retrieve single book
+- Verify review count
+- Verify average rating accuracy
+
+**`tests/test_add_review.py`** - 
+- Filtering by min_rating
+- Boundary rating values
+- Invalid min_rating handling
+- Multiple book scenarios
+
+## 📁 Project Structure
+
+```
+spec-driven-development/
+├── app/
+│   ├── main.py        # FastAPI routes
+│   ├── schemas.py     # Pydantic validation
+│   └── crud.py        # In-memory business logic
+├── tests/
+│   ├── conftest.py    # Storage reset fixture
+│   ├── test_create_book.py
+│   ├── test_add_review.py
+│   ├── test_list_books.py
+│   └── test_filter_books.py
+├── SPECS/
+│   ├── 01-create-book.md
+│   ├── 02-add-review.md
+│   ├── 03-list-books.md
+│   ├── 04-filter-books.md
+│   ├── 05-get-book-by-id.md
+│   ├── 06-list-reviews.md
+│   └── 07-testing-framework.md
+├── requirements.txt
+├── RULES.md
+├── TODO.md
+└── README.md
+```
+
+## 🛠️ Development Approach
+
+This project was built following **spec-driven development** using AI code generation tools (Claude):
+
+1. **Specification First**: Created detailed feature specs in `SPECS/` directory before any code
+2. **Incremental Implementation**: Built features one at a time following the specs
+3. **Test-Driven**: Wrote comprehensive tests alongside implementation
+4. **Iterative Refinement**: Used AI to accelerate development while maintaining quality
+
+### Tools Used
+- **Claude (AI Assistant)**: Primary code generation and development assistance
+- **FastAPI**: Modern, fast Python web framework
+- **Pytest**: Testing framework
+- **Pydantic**: Data validation
+- **Uvicorn**: ASGI server
+
+## 📊 Test Coverage
+
+The test suite covers:
+- ✅ All CRUD operations
+- ✅ All filtering and search scenarios
+- ✅ Happy paths and success cases
+- ✅ Error conditions (404, 422)
+- ✅ Edge cases (empty data, boundary values)
+- ✅ Input validation
+- ✅ Special characters and Unicode
+- ✅ Concurrent operations
+
+Run `pytest --cov=app` to generate a coverage report.

SPECS/001-create-book.md

@@ -0,0 +1,29 @@
+# Feature 001 — Create Book
+
+## Description
+Allow clients to create a new Book resource in the system.
+
+All book fields are required.
+
+## Endpoint
+POST /books
+
+## Request Body (JSON)
+
+{
+  "title": "string",
+  "author": "string",
+  "published_year": 2024,
+  "genre": "string",
+  "description": "string"
+}
+
+## Validation Rules
+
+- title must not be empty
+- author must not be empty
+- genre must not be empty
+- description must not be empty
+- published_year must be:
+  - a positive integer
+  - not greater than the curren

SPECS/002-add-review.md

@@ -0,0 +1,61 @@
+# Feature 002 — Add Review to Book
+
+## Description
+
+Allow clients to add a review to an existing Book.
+
+Each review:
+- Must belong to an existing Book
+- Must contain rating and comment
+- Must update the book's average_rating
+
+## Endpoint
+
+POST /books/{book_id}/reviews
+
+## Request Body (JSON)
+
+{
+  "rating": 4,
+  "comment": "Excellent book"
+}
+
+## Validation Rules
+
+- book_id must exist
+- rating must be:
+  - integer
+  - between 1 and 5 (inclusive)
+- comment must not be empty
+
+## Business Rules
+
+- After a review is added:
+  - The book's average_rating must be recalculated
+  - average_rating = mean of all ratings for that book
+
+## Success Response
+
+Status: 201 Created
+
+{
+  "id": 1,
+  "book_id": 1,
+  "rating": 4,
+  "comment": "Excellent book"
+}
+
+## Error Responses
+
+404 Not Found:
+- If book does not exist
+
+400 Bad Request:
+- Invalid rating
+- Empty comment
+
+## Acceptance Criteria
+
+- A valid review is saved in database.
+- Review is linked to correct book.
+- Book average_rating is updated corr_

SPECS/003-list-books.md

@@ -0,0 +1,54 @@
+# Feature 003 — List Books
+
+## Description
+
+Allow clients to retrieve all books in the system.
+
+Books should include:
+- All required fields
+- Computed average_rating
+- Total number of reviews
+
+## Endpoint
+
+GET /books
+
+## Query Parameters
+
+None (basic listing for this feature)
+
+## Success Response
+
+Status: 200 OK
+
+[
+  {
+    "id": 1,
+    "title": "string",
+    "author": "string",
+    "published_year": 2024,
+    "genre": "string",
+    "description": "string",
+    "average_rating": 4.5,
+    "review_count": 2
+  }
+]
+
+## Business Rules
+
+- If no books exist, return an empty list.
+- average_rating must reflect current value.
+- review_count must match number of reviews.
+
+## Acceptance Criteria
+
+- Returns 200 OK.
+- Returns list of all books.
+- Includes review_count.
+- Empty database returns [].
+- Multiple books are returned correctly.
+- Tests must cover:
+  - Empty list
+  - Single book
+  - Multiple books
+  - Correct review_count