Task Manager API - Spec-Driven Development - Vinay

spec-driven-development/SETUP.md

@@ -0,0 +1,345 @@
+# Setup and Usage Guide
+
+This document explains how to set up and run the Task Manager REST API.
+
+> **Note:** This is the user documentation. See `README.md` for assessment details.
+
+---
+
+## Prerequisites
+
+- **Python 3.7+** installed on your system
+- **pip** package installer
+- **Git** (for cloning the repository)
+
+---
+
+## Installation
+
+### 1. Clone the Repository
+
+```bash
+git clone https://github.com/automationExamples/spec-driven-development.git
+cd spec-driven-development
+```
+
+### 2. Create Virtual Environment
+
+**Windows:**
+```powershell
+python -m venv venv
+.\venv\Scripts\activate
+```
+
+**Linux/Mac:**
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+
+### 3. Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+Expected packages:
+- Flask 3.1.0
+- Flask-CORS 5.0.0
+- pytest 8.3.4
+- requests 2.32.3
+
+---
+
+## Running the Application
+
+### Start the Server
+
+```bash
+python app.py
+```
+
+Expected output:
+```
+============================================================
+🚀 Task Manager API Starting
+============================================================
+📋 Specification: SPECS/task-manager-api.md
+📝 Sample tasks loaded: 3
+🌐 Server: http://localhost:5000
+💚 Health check: http://localhost:5000/health
+============================================================
+```
+
+The API will be available at **http://localhost:5000**
+
+### Verify It's Running
+
+Open a browser or use curl:
+
+```bash
+curl http://localhost:5000/health
+```
+
+Expected response:
+```json
+{
+  "status": "healthy",
+  "message": "Task Manager API is running"
+}
+```
+
+---
+
+## Running Tests
+
+### Run All Tests
+
+```bash
+pytest test_app.py -v
+```
+
+Expected output:
+```
+================================ test session starts =================================
+collected 31 items
+
+test_app.py::TestHealthCheck::test_health_check PASSED                         [  3%]
+test_app.py::TestGetTasks::test_get_tasks_empty PASSED                         [  6%]
+...
+================================ 31 passed in 0.23s ==================================
+```
+
+### Run Specific Test Class
+
+```bash
+pytest test_app.py::TestCreateTask -v
+```
+
+### Run with Coverage Report
+
+```bash
+pytest test_app.py -v --cov=app --cov-report=term-missing
+```
+
+---
+
+## API Usage Examples
+
+### Using curl
+
+**Get all tasks:**
+```bash
+curl http://localhost:5000/tasks
+```
+
+**Get pending tasks:**
+```bash
+curl http://localhost:5000/tasks?status=pending
+```
+
+**Get single task:**
+```bash
+curl http://localhost:5000/tasks/1
+```
+
+**Create a task:**
+```bash
+curl -X POST http://localhost:5000/tasks \
+  -H "Content-Type: application/json" \
+  -d '{"title":"New Task","description":"Task description","status":"pending"}'
+```
+
+**Update a task:**
+```bash
+curl -X PUT http://localhost:5000/tasks/1 \
+  -H "Content-Type: application/json" \
+  -d '{"status":"completed"}'
+```
+
+**Delete a task:**
+```bash
+curl -X DELETE http://localhost:5000/tasks/1
+```
+
+**Get statistics:**
+```bash
+curl http://localhost:5000/tasks/stats
+```
+
+### Using Python requests
+
+```python
+import requests
+
+# Get all tasks
+response = requests.get('http://localhost:5000/tasks')
+print(response.json())
+
+# Create a task
+new_task = {
+    'title': 'New Task',
+    'description': 'Description',
+    'status': 'pending'
+}
+response = requests.post('http://localhost:5000/tasks', json=new_task)
+print(response.json())
+
+# Update a task
+update_data = {'status': 'completed'}
+response = requests.put('http://localhost:5000/tasks/1', json=update_data)
+print(response.json())
+```
+
+### Using a Browser
+
+1. Open browser to **http://localhost:5000/health**
+2. For GET requests, use the address bar:
+   - http://localhost:5000/tasks
+   - http://localhost:5000/tasks/1
+   - http://localhost:5000/tasks/stats
+
+For POST/PUT/DELETE, use a tool like:
+- **Postman** (https://www.postman.com/)
+- **Insomnia** (https://insomnia.rest/)
+- **Thunder Client** (VS Code extension)
+
+---
+
+## API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/health` | Health check |
+| GET | `/tasks` | List all tasks (optional ?status filter) |
+| GET | `/tasks/{id}` | Get single task |
+| POST | `/tasks` | Create new task |
+| PUT | `/tasks/{id}` | Update task |
+| DELETE | `/tasks/{id}` | Delete task |
+| GET | `/tasks/stats` | Get task statistics |
+
+For detailed endpoint specifications, see `SPECS/task-manager-api.md`
+
+---
+
+## Project Structure
+
+```
+spec-driven-development/
+├── SPECS/
+│   └── task-manager-api.md    # Feature specification
+├── app.py                      # Flask application
+├── test_app.py                 # Test suite  
+├── requirements.txt            # Python dependencies
+├── TODO.md                     # Implementation tracking
+├── SETUP.md                    # This file
+├── README.md                   # Assessment documentation
+└── RULES.md                    # Development rules
+```
+
+---
+
+## Development Workflow
+
+This project follows **spec-driven development**:
+
+1. **Specification First** - Feature defined in SPECS/ before coding
+2. **Implementation** - Code written to match specification exactly
+3. **Testing** - Tests validate all acceptance criteria
+4. **Documentation** - Clear setup and usage instructions
+
+See `RULES.md` for the complete workflow.
+
+---
+
+## Troubleshooting
+
+### Port 5000 Already in Use
+
+**Error:** `Address already in use`
+
+**Solution:**
+```bash
+# Find process using port 5000
+# Windows:
+netstat -ano | findstr :5000
+
+# Linux/Mac:
+lsof -i :5000
+
+# Kill the process or change port in app.py
+```
+
+### Module Not Found
+
+**Error:** `ModuleNotFoundError: No module named 'flask'`
+
+**Solution:**
+```bash
+# Make sure virtual environment is activated
+# Windows:
+.\venv\Scripts\activate
+
+# Linux/Mac:
+source venv/bin/activate
+
+# Reinstall dependencies
+pip install -r requirements.txt
+```
+
+### Tests Failing
+
+**Issue:** Tests fail with connection errors
+
+**Solution:**
+- Make sure Flask server is NOT running when running tests
+- Tests use Flask test client, not live server
+- If server is running, stop it first
+
+---
+
+## Sample Data
+
+The application starts with 3 sample tasks:
+
+1. **ID 1:** "Complete assessment" (in_progress)
+2. **ID 2:** "Review documentation" (pending)
+3. **ID 3:** "Write tests" (completed)
+
+Sample data is loaded automatically when you run `python app.py`
+
+---
+
+## Stopping the Application
+
+Press `Ctrl + C` in the terminal where the server is running.
+
+---
+
+## Deactivating Virtual Environment
+
+```bash
+deactivate
+```
+
+---
+
+## Additional Resources
+
+- **Flask Documentation:** https://flask.palletsprojects.com/
+- **pytest Documentation:** https://docs.pytest.org/
+- **REST API Best Practices:** https://restfulapi.net/
+
+---
+
+## Support
+
+For issues or questions about this assessment project, refer to:
+- Feature specification: `SPECS/task-manager-api.md`
+- Development rules: `RULES.md`
+- Assessment requirements: `README.md`
+
+---
+
+**Last Updated:** 2026-02-11  
+**Version:** 1.0