Skip to content

Instantly share code, notes, and snippets.

@tariqulislam

tariqulislam/plan information for prompts

Created February 19, 2026 02:16
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save tariqulislam/f2c2f10d861e22d42645e7bad9338338 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save tariqulislam/f2c2f10d861e22d42645e7bad9338338 to your computer and use it in GitHub Desktop.
Download ZIP
Output of @prompts/cores/build_backend_api_core.md prompts command
Raw
plan information for prompts
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Plan to implement │
│ │
│ Backend REST API Implementation Plan │
│ │
│ Context │
│ │
│ This project currently has a complete MySQL ecommerce database with Users, Products, and Cart tables, managed through Claude Code custom skills (/setup-db, │
│ /check-schema, /seed-data, /query-db). The database is operational and accessible via the MCP server my-project-db. │
│ │
│ Current state: No backend API code exists yet - this is a greenfield implementation. │
│ │
│ Goal: Build a production-ready Python REST API using Bottle framework to expose full CRUD operations for all three database tables, with Swagger UI │
│ documentation for interactive API testing. │
│ │
│ Architecture Decisions │
│ │
│ Core Stack │
│ │
│ - Framework: Bottle (lightweight, perfect for this scale) │
│ - ORM: Peewee (simple, Django-like syntax, excellent MySQL support, lighter than SQLAlchemy) │
│ - Validation: Marshmallow (schema validation and serialization) │
│ - Swagger: bottle-swagger + OpenAPI 3.0 spec │
│ - Server: Waitress (production WSGI server) │
│ - CORS: bottle-cors-plugin │
│ │
│ Project Structure │
│ │
│ backend/ │
│ ├── app.py # Main application entry point │
│ ├── config.py # Environment variable loader (.env) │
│ ├── database.py # Peewee database connection │
│ ├── models/ # ORM models │
│ │ ├── user.py # User model │
│ │ ├── product.py # Product model │
│ │ └── cart.py # Cart model (with ForeignKeys) │
│ ├── routes/ # API endpoints │
│ │ ├── users.py # /api/users endpoints │
│ │ ├── products.py # /api/products endpoints │
│ │ └── cart.py # /api/cart endpoints │
│ ├── schemas/ # Marshmallow validation schemas │
│ │ ├── user_schema.py │
│ │ ├── product_schema.py │
│ │ └── cart_schema.py │
│ ├── middleware/ # Error handling, CORS │
│ │ ├── error_handler.py │
│ │ └── cors.py │
│ ├── utils/ # Helper functions │
│ │ ├── response.py # Standardized JSON responses │
│ │ └── validators.py │
│ ├── swagger/ # API documentation │
│ │ ├── swagger.json # OpenAPI 3.0 specification │
│ │ └── swagger_ui.py # Swagger UI setup │
│ ├── requirements.txt # Python dependencies │
│ └── README.md # Usage documentation │
│ │
│ API Endpoints (17 total) │
│ │
│ Users (/api/users) │
│ │
│ - GET /api/users - List all users (passwords excluded) │
│ - GET /api/users/:id - Get single user │
│ - POST /api/users - Create user │
│ - PUT /api/users/:id - Update user │
│ - DELETE /api/users/:id - Delete user (CASCADE removes cart items) │
│ - GET /api/users/:id/cart - Get user's cart items with product details │
│ │
│ Products (/api/products) │
│ │
│ - GET /api/products - List all products │
│ - GET /api/products/:id - Get single product │
│ - POST /api/products - Create product │
│ - PUT /api/products/:id - Update product │
│ - DELETE /api/products/:id - Delete product (CASCADE removes cart items) │
│ - GET /api/products/:id/carts - Get carts containing this product │
│ │
│ Cart (/api/cart) │
│ │
│ - GET /api/cart - List all cart items (with user + product relations) │
│ - GET /api/cart/:id - Get single cart item │
│ - POST /api/cart - Add item to cart (validates foreign keys) │
│ - DELETE /api/cart/:id - Remove cart item │
│ - DELETE /api/cart/user/:user_id - Clear user's entire cart │
│ │
│ Standard Response Format │
│ │
│ // Success │
│ { │
│ "success": true, │
│ "data": {...}, │
│ "message": "Operation completed" │
│ } │
│ │
│ // Error │
│ { │
│ "success": false, │
│ "error": { │
│ "code": "VALIDATION_ERROR", │
│ "message": "Email is required" │
│ } │
│ } │
│ │
│ Implementation Steps │
│ │
│ Phase 1: Foundation (5 files) │
│ │
│ 1. Create backend/requirements.txt with dependencies: │
│ - bottle, peewee, PyMySQL, python-dotenv, bottle-swagger, marshmallow, bottle-cors-plugin, waitress │
│ 2. Create backend/config.py - Load .env variables (DB credentials + BOTTLE_SERVER_PORT) │
│ 3. Create backend/database.py - Initialize Peewee MySQL connection using .env credentials │
│ 4. Update .env - Add BOTTLE_SERVER_PORT=8088 │
│ 5. Create backend/models/__init__.py - Model registry │
│ │
│ Phase 2: ORM Models (3 files) │
│ │
│ 1. Create backend/models/user.py │
│ - Fields: id (PK), email (unique), password, role (ENUM: ADMIN/USER) │
│ - Method: to_dict(exclude_password=True) │
│ 2. Create backend/models/product.py │
│ - Fields: id (PK), title, image_url (nullable), description (nullable) │
│ - Method: to_dict() │
│ 3. Create backend/models/cart.py │
│ - Fields: id (PK), product_id (FK), user_id (FK) │
│ - ForeignKeyField with on_delete='CASCADE' for both relations │
│ - Method: to_dict_with_relations() - includes nested user + product │
│ │
│ Critical: Models must use existing table names and match current schema exactly (no migrations needed) │
│ │
│ Phase 3: Validation Schemas (4 files) │
│ │
│ 1. Create backend/schemas/user_schema.py │
│ - UserCreateSchema (email, password, role required; validate role ENUM) │
│ - UserUpdateSchema (all optional) │
│ - UserResponseSchema (exclude password) │
│ 2. Create backend/schemas/product_schema.py │
│ - ProductCreateSchema (title required) │
│ - ProductUpdateSchema (all optional) │
│ 3. Create backend/schemas/cart_schema.py │
│ - CartCreateSchema (user_id, product_id required; validate foreign keys exist) │
│ - CartResponseSchema (include nested relations) │
│ 4. Create backend/schemas/__init__.py │
│ │
│ Phase 4: Utilities & Middleware (5 files) │
│ │
│ 1. Create backend/utils/response.py │
│ - success_response(data, message) - Standard success format │
│ - error_response(code, message, status) - Standard error format │
│ 2. Create backend/utils/validators.py │
│ - validate_email(email) - Email format validation │
│ - validate_foreign_key(model, id) - Check if FK exists │
│ 3. Create backend/middleware/error_handler.py │
│ - Centralized error handler decorator │
│ - Map Peewee exceptions to HTTP codes (IntegrityError → 409, DoesNotExist → 404) │
│ 4. Create backend/middleware/cors.py │
│ - Configure CORS for development (allow all origins) │
│ 5. Create backend/utils/__init__.py and backend/middleware/__init__.py │
│ │
│ Phase 5: API Routes (4 files) │
│ │
│ 1. Create backend/routes/users.py - Implement all 6 user endpoints │
│ - Validate schemas with Marshmallow │
│ - Handle CASCADE deletes (inform user that cart items were removed) │
│ - Exclude passwords from all responses │
│ 2. Create backend/routes/products.py - Implement all 6 product endpoints │
│ - Handle CASCADE deletes │
│ 3. Create backend/routes/cart.py - Implement all 5 cart endpoints │
│ - Validate foreign keys before INSERT │
│ - Return nested relations (user + product data) │
│ - Handle IntegrityError for invalid FKs │
│ 4. Create backend/routes/__init__.py - Route registration function │
│ │
│ Phase 6: Swagger Documentation (3 files) │
│ │
│ 1. Create backend/swagger/swagger.json │
│ - Complete OpenAPI 3.0 specification │
│ - Define all 17 endpoints with request/response schemas │
│ - Include examples for each operation │
│ - Define error response schemas │
│ 2. Create backend/swagger/swagger_ui.py │
│ - Serve swagger.json at /api/swagger.json │
│ - Serve Swagger UI at /api/docs (use CDN for static assets) │
│ 3. Create backend/swagger/__init__.py │
│ │
│ Phase 7: Main Application (1 file) │
│ │
│ 1. Create backend/app.py │
│ - Initialize Bottle application │
│ - Load configuration from config.py │
│ - Initialize database connection (test connection on startup) │
│ - Register CORS middleware │
│ - Register error handler middleware │
│ - Register all routes (users, products, cart) │
│ - Register Swagger UI │
│ - Add GET /health endpoint (database connection check) │
│ - Add GET / endpoint (API information) │
│ - Configure Waitress server on port 8088 │
│ - Main entry point: if __name__ == '__main__': run() │
│ │
│ Phase 8: Documentation (1 file) │
│ │
│ 1. Create backend/README.md │
│ - Installation instructions │
│ - Environment setup guide │
│ - Running the server │
│ - API endpoint reference (with curl examples) │
│ - Swagger UI usage │
│ - Database schema overview │
│ - Troubleshooting guide │
│ │
│ Critical Files │
│ │
│ 1. backend/app.py - Main entry point that integrates all components │
│ 2. backend/models/cart.py - Most complex model with CASCADE foreign keys │
│ 3. backend/routes/cart.py - Most complex routes requiring FK validation │
│ 4. backend/database.py - Foundation for all database operations │
│ 5. backend/swagger/swagger.json - Complete API documentation │
│ │
│ Error Handling Strategy │
│ │
│ HTTP Status Codes │
│ │
│ - 200 OK - Successful GET, PUT, DELETE │
│ - 201 Created - Successful POST │
│ - 400 Bad Request - Validation errors (missing fields, invalid data) │
│ - 404 Not Found - Resource doesn't exist │
│ - 409 Conflict - Foreign key constraint violations, duplicate email │
│ - 500 Internal Server Error - Database errors │
│ │
│ CASCADE Delete Handling │
│ │
│ - When deleting User → Auto-removes all their Cart items │
│ - When deleting Product → Auto-removes all Cart items containing it │
│ - API returns success with message about CASCADE effects │
│ │
│ Foreign Key Validation │
│ │
│ - Before creating Cart item, validate user_id and product_id exist │
│ - Catch Peewee IntegrityError and return 409 with clear message │
│ │
│ Dependencies (requirements.txt) │
│ │
│ bottle==0.12.25 │
│ peewee==3.17.0 │
│ PyMySQL==1.1.0 │
│ python-dotenv==1.0.0 │
│ bottle-swagger==0.3.0 │
│ marshmallow==3.20.1 │
│ bottle-cors-plugin==0.1.9 │
│ waitress==2.1.2 │
│ │
│ Environment Configuration (.env updates) │
│ │
│ # Add to existing .env: │
│ BOTTLE_SERVER_PORT=8088 │
│ BOTTLE_DEBUG=true │
│ BOTTLE_RELOADER=true │
│ CORS_ALLOW_ORIGIN=* │
│ │
│ Verification & Testing │
│ │
│ Step 1: Install and Run │
│ │
│ cd backend │
│ pip install -r requirements.txt │
│ python app.py │
│ │
│ Step 2: Swagger UI Testing │
│ │
│ - Open http://localhost:8088/api/docs │
│ - Test all CRUD operations for each entity │
│ - Verify error handling (try invalid data) │
│ - Test foreign key validation │
│ - Test CASCADE deletes │
│ │
│ Step 3: Manual Testing │
│ │
│ # Create user │
│ curl -X POST http://localhost:8088/api/users \ │
│ -H "Content-Type: application/json" \ │
│ -d '{"email":"test@example.com","password":"secret","role":"USER"}' │
│ │
│ # Create product │
│ curl -X POST http://localhost:8088/api/products \ │
│ -H "Content-Type: application/json" \ │
│ -d '{"title":"Test Product"}' │
│ │
│ # Add to cart │
│ curl -X POST http://localhost:8088/api/cart \ │
│ -H "Content-Type: application/json" \ │
│ -d '{"user_id":1,"product_id":1}' │
│ │
│ # Get user's cart │
│ curl http://localhost:8088/api/users/1/cart │
│ │
│ # Test CASCADE delete │
│ curl -X DELETE http://localhost:8088/api/users/1 │
│ │
│ Step 4: Database Consistency Check │
│ │
│ # In Claude Code │
│ /query-db SELECT COUNT(*) FROM users │
│ /query-db SELECT COUNT(*) FROM products │
│ /query-db SELECT COUNT(*) FROM cart │
│ │
│ # Compare counts with API responses │
│ curl http://localhost:8088/api/users | jq 'length' │
│ curl http://localhost:8088/api/products | jq 'length' │
│ curl http://localhost:8088/api/cart | jq 'length' │
│ │
│ Step 5: CASCADE Behavior Verification │
│ │
│ 1. Create user with cart items │
│ 2. Delete user via API │
│ 3. Verify cart items were removed: /query-db SELECT * FROM cart WHERE user_id=X │
│ 4. Repeat for product deletion │
│ │
│ Success Criteria │
│ │
│ ✅ Server starts successfully on port 8088 │
│ ✅ Swagger UI accessible at http://localhost:8088/api/docs │
│ ✅ All 17 endpoints return expected responses │
│ ✅ Validation rejects invalid data with clear error messages │
│ ✅ Foreign key constraints enforced (can't add cart item with invalid user/product) │
│ ✅ CASCADE deletes work correctly │
│ ✅ Passwords never exposed in responses │
│ ✅ Error handling returns appropriate HTTP status codes │
│ ✅ API data matches database queries via /query-db │
│ ✅ README.md provides clear usage instructions │
│ │
│ File Creation Order │
│ │
│ Must be created in this exact order to avoid import errors: │
│ │
│ 1. backend/requirements.txt │
│ 2. backend/config.py │
│ 3. backend/database.py │
│ 4. backend/models/user.py │
│ 5. backend/models/product.py │
│ 6. backend/models/cart.py (depends on User + Product) │
│ 7. backend/models/init.py │
│ 8. backend/schemas/user_schema.py │
│ 9. backend/schemas/product_schema.py │
│ 10. backend/schemas/cart_schema.py │
│ 11. backend/schemas/init.py │
│ 12. backend/utils/response.py │
│ 13. backend/utils/validators.py │
│ 14. backend/utils/init.py │
│ 15. backend/middleware/error_handler.py │
│ 16. backend/middleware/cors.py │
│ 17. backend/middleware/init.py │
│ 18. backend/routes/users.py │
│ 19. backend/routes/products.py │
│ 20. backend/routes/cart.py │
│ 21. backend/routes/init.py │
│ 22. backend/swagger/swagger.json │
│ 23. backend/swagger/swagger_ui.py │
│ 24. backend/swagger/init.py │
│ 25. backend/app.py │
│ 26. backend/README.md │
│ 27. .env (update with BOTTLE_SERVER_PORT) │
│ │
│ Notes │
│ │
│ - No schema changes: Models will connect to existing tables, no migrations needed │
│ - Peewee introspection: Can use pwiz.py tool to verify model definitions match actual schema │
│ - Password security: For production, add bcrypt hashing (not in initial implementation) │
│ - Authentication: JWT authentication is a future enhancement (not in scope) │
│ - Pagination: List endpoints return all records (add pagination in future if needed) │
│ - Existing data: API will work with data created by /seed-data skill immediately │
╰───────────────────────────
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment