docs: Expand README with comprehensive API design details, including endpoints, request/response models, and security features

Author: coder7475

README.md

@@ -290,6 +290,167 @@ Query Results (JSON):
 ]
 ```
 
+## API Design
+
+### Overview
+
+The Text2SQL Analytics System exposes a RESTful API built with **FastAPI** that converts natural language queries into SQL and executes them against a PostgreSQL database. The API includes built-in security features, rate limiting, and comprehensive error handling.
+
+### Base URL
+
+```
+http://localhost:8000
+```
+
+### Authentication & Security
+
+- **Rate Limiting**: 5 requests per 10 seconds per IP address
+- **Request Timeout**: Monitored via `X-Process-Time` header
+- **SQL Injection Protection**: Built-in query validation and sanitization
+- **Error Handling**: Structured error responses with appropriate HTTP status codes
+
+### Endpoints
+
+#### 1. Health Check
+
+**GET** `/`
+
+Returns the API health status.
+
+**Response:**
+
+```json
+{
+  "status": "ok",
+  "message": "Text2SQL API running."
+}
+```
+
+#### 2. Generate and Execute SQL
+
+**POST** `/generate-sql`
+
+Converts natural language to SQL, validates the query, and executes it against the database.
+
+**Request Body:**
+
+```json
+{
+  "question": "Show all orders shipped in 1997"
+}
+```
+
+**Response Schema:**
+
+```json
+{
+  "sql_query": "string", // Raw SQL generated by Gemini
+  "sanitized_query": "string", // SQL after sanitization
+  "validate_query": "string", // Final validated SQL
+  "result_json": "string" // Query results as JSON string
+}
+```
+
+**Example Request:**
+
+```bash
+curl -X POST "http://localhost:8000/generate-sql" \
+     -H "Content-Type: application/json" \
+     -d '{"question": "Find all customers from Germany"}'
+```
+
+**Example Response:**
+
+```json
+{
+  "sql_query": "SELECT * FROM customers WHERE country = 'Germany';",
+  "sanitized_query": "SELECT * FROM customers WHERE country = 'Germany'",
+  "validate_query": "SELECT * FROM customers WHERE country = 'Germany'",
+  "result_json": "[{\"customer_id\":1,\"company_name\":\"Alfreds Futterkiste\",\"country\":\"Germany\"}]"
+}
+```
+
+### Error Responses
+
+#### 400 Bad Request
+
+```json
+{
+  "detail": "Validation error: Invalid SQL syntax"
+}
+```
+
+#### 429 Too Many Requests
+
+```json
+{
+  "message": "Too many requests"
+}
+```
+
+#### 500 Internal Server Error
+
+```json
+{
+  "detail": "Internal error: Database connection failed"
+}
+```
+
+### Request/Response Models
+
+**Text2SQLRequest:**
+
+- `question` (string, required): Natural language query
+- Default: "Show all orders shipped in 1997"
+
+**SQLResponseModel:**
+
+- `sql_query` (string): Original SQL generated by Gemini API
+- `sanitized_query` (string): SQL after sanitization process
+- `validate_query` (string): Final validated SQL ready for execution
+- `result_json` (string): Query results serialized as JSON
+
+### API Features
+
+#### Middleware Stack
+
+1. **Process Time Tracking**: Adds `X-Process-Time` header to all responses
+2. **Rate Limiting**: IP-based request limiting (5 req/10sec)
+3. **CORS**: Cross-origin resource sharing support
+
+#### Query Processing Pipeline
+
+1. **Natural Language Input**: User provides English question
+2. **Prompt Engineering**: Question converted to optimized prompt
+3. **SQL Generation**: Gemini API generates SQL query
+4. **Sanitization**: Remove dangerous SQL constructs
+5. **Validation**: Ensure SQL syntax and safety
+6. **Execution**: Run validated query against PostgreSQL
+7. **Serialization**: Convert results to JSON format
+
+#### Supported Query Types
+
+- **SELECT queries**: Data retrieval operations
+- **Aggregations**: COUNT, SUM, AVG, MIN, MAX
+- **Joins**: Inner, left, right joins across tables
+- **Filtering**: WHERE clauses with various conditions
+- **Grouping**: GROUP BY with HAVING clauses
+- **Sorting**: ORDER BY operations
+
+#### Blocked Operations
+
+- INSERT, UPDATE, DELETE statements
+- DROP, ALTER, CREATE statements
+- System function calls
+- Subqueries with potential security risks
+
+### Interactive Documentation
+
+FastAPI automatically generates interactive API documentation:
+
+- **Swagger UI**: [http://localhost:8000/docs](http://localhost:8000/docs)
+- **ReDoc**: [http://localhost:8000/redoc](http://localhost:8000/redoc)
+
 ## Running the FastAPI Application
 
 To start the development server with hot-reload, run:
@@ -298,8 +459,19 @@ To start the development server with hot-reload, run:
 uvicorn src.main:app --reload
 ```
 
-The API will be available at [http://localhost:8000](http://localhost:8000).  
-Access the automatically generated interactive documentation at [http://localhost:8000/docs](http://localhost:8000/docs) or the alternative ReDoc at [http://localhost:8000/redoc](http://localhost:8000/redoc).
+The API will be available at [http://localhost:8000](http://localhost:8000).
+
+### Production Deployment
+
+For production deployment, use:
+
+```bash
+# With specific host and port
+uvicorn src.main:app --host 0.0.0.0 --port 8000
+
+# With multiple workers
+uvicorn src.main:app --host 0.0.0.0 --port 8000 --workers 4
+```
 
 ## Testing