Merge pull request #19 from mdhishaamakhtar/master

Author: AdityaSareen06

.coverage

@@ -7,8 +7,9 @@ The Iris Wikipedia Pathfinder API finds the shortest path between two Wikipedia
 ## Base URL
 
 ```
-API: http://localhost:9020
-Web UI: http://localhost:9020/ui
+Application: http://localhost:9020
+Interactive UI: http://localhost:9020 (default landing page)
+API Documentation: http://localhost:9020/api
 ```
 
 ## Quick Start
@@ -96,10 +97,20 @@ honcho start
 
 ## API Endpoints
 
-### 1. Root Endpoint - API Information
+### 1. Interactive UI (Landing Page)
 
 **GET /**
 
+Serves the interactive web interface for pathfinding visualization (default landing page).
+
+**GET /any-path**
+
+All non-API paths automatically redirect to the main UI for a seamless user experience.
+
+### 2. API Information
+
+**GET /api**
+
 Returns basic API information and available endpoints.
 
 **Response:**
@@ -113,14 +124,15 @@ Returns basic API information and available endpoints.
     "GET /tasks/status/<task_id>": "Check task status",
     "POST /explore": "Explore page connections",
     "GET /health": "Health check",
-    "GET /ui": "Interactive web interface",
-    "GET /": "API information"
+    "GET /": "Interactive web interface",
+    "GET /api": "API information"
   },
-  "documentation": "./API_DOCUMENTATION.md"
+  "documentation": "./API_DOCUMENTATION.md",
+  "ui_url": "/"
 }
 ```
 
-### 2. Find Path Between Pages
+### 3. Find Path Between Pages
 
 **POST /getPath**
 
@@ -164,7 +176,7 @@ curl -X POST http://localhost:9020/getPath \
   }'
 ```
 
-### 3. Check Task Status
+### 4. Check Task Status
 
 **GET /tasks/status/{task_id}**
 
@@ -173,29 +185,39 @@ Polls the status of a pathfinding task.
 **Path Parameters:**
 - `task_id` (string, required): Task ID returned from /getPath
 
-**Response - Task Pending:**
+**Response — PENDING:**
 ```json
 {
-  "status": "PENDING", 
+  "status": "PENDING",
   "task_id": "abc123-def456-ghi789",
   "message": "Task is waiting to be processed"
 }
 ```
 
-**Response - Task In Progress:**
+**Response — IN_PROGRESS:**
 ```json
 {
   "status": "IN_PROGRESS",
-  "task_id": "abc123-def456-ghi789", 
+  "task_id": "abc123-def456-ghi789",
   "progress": {
-    "current_depth": 3,
-    "nodes_explored": 150,
-    "message": "Searching at depth 3..."
+    "status": "Starting pathfinding search...",
+    "search_stats": {
+      "nodes_explored": 0,
+      "current_depth": 0,
+      "last_node": "Albert Einstein",
+      "queue_size": 1,
+      "start_page": "Albert Einstein",
+      "end_page": "Physics",
+      "max_depth": 6
+    },
+    "search_time_elapsed": 0
   }
 }
 ```
 
-**Response - Task Success:**
+Note: The `progress` object mirrors the task's meta and may include additional fields depending on runtime.
+
+**Response — SUCCESS:**
 ```json
 {
   "status": "SUCCESS",
@@ -204,12 +226,22 @@ Polls the status of a pathfinding task.
     "path": ["Albert Einstein", "Science", "Physics"],
     "length": 3,
     "search_time": 2.45,
-    "nodes_explored": 287
+    "nodes_explored": 287,
+    "search_stats": {
+      "nodes_explored": 287,
+      "final_depth": 2,
+      "start_page": "Albert Einstein",
+      "end_page": "Physics",
+      "max_depth": 6,
+      "search_completed": true
+    }
   }
 }
 ```
 
-**Response - Task Failed:**
+Note: If the underlying task returns a different structure, it may be passed through as-is in `result`.
+
+**Response — FAILURE:**
 ```json
 {
   "status": "FAILURE",
@@ -218,12 +250,23 @@ Polls the status of a pathfinding task.
 }
 ```
 
+**Response — Other States (e.g., RETRY):**
+```json
+{
+  "status": "RETRY",
+  "task_id": "abc123-def456-ghi789",
+  "info": "Retrying due to: Connection timeout to Wikipedia API"
+}
+```
+
+Note: For states other than the above, `info` contains a string description derived from the task's state/meta.
+
 **Example cURL:**
 ```bash
 curl http://localhost:9020/tasks/status/abc123-def456-ghi789
 ```
 
-### 4. Explore Page Connections
+### 5. Explore Page Connections
 
 **POST /explore**
 
@@ -272,7 +315,7 @@ curl -X POST http://localhost:9020/explore \
   }'
 ```
 
-### 5. Health Check
+### 6. Health Check
 
 **GET /health**
 
@@ -283,7 +326,7 @@ Checks the health status of all system components.
 {
   "status": "healthy",
   "redis_status": "healthy",
-  "cache_status": "healthy", 
+  "cache_status": "healthy",
   "wikipedia_api_status": "healthy",
   "timestamp": "2025-01-31T00:00:00Z"
 }
@@ -295,7 +338,7 @@ Checks the health status of all system components.
   "status": "degraded",
   "redis_status": "unhealthy: Connection refused",
   "cache_status": "healthy",
-  "wikipedia_api_status": "healthy", 
+  "wikipedia_api_status": "healthy",
   "timestamp": "2025-01-31T00:00:00Z"
 }
 ```
@@ -305,7 +348,7 @@ Checks the health status of all system components.
 curl http://localhost:9020/health
 ```
 
-### 6. Clear Cache (Admin)
+### 7. Clear Cache (Admin)
 
 **POST /cache/clear**
 
@@ -337,24 +380,27 @@ curl -X POST http://localhost:9020/cache/clear \
   -d '{"pattern": "wiki_links:*"}'
 ```
 
-### 7. Interactive Web Interface
+### 8. Interactive Web Interface Features
 
-**GET /ui**
+The main landing page (`/`) serves the interactive web interface with enhanced features:
 
-Serves the interactive web interface for visualizing Wikipedia pathfinding results.
-
-**Features:**
+**Enhanced Features:**
+- **UI-First Experience**: Landing page serves interactive UI directly, all paths redirect to main interface
+- **State Persistence**: Automatically saves and restores search state using localStorage
+- **Mobile-Optimized**: Fixed touch/scroll conflicts for seamless mobile graph interaction
+- **Session Recovery**: Automatically resumes interrupted searches after page refresh
 - **Modern Dark Theme**: Professional dark tech aesthetic with GitHub-inspired colors
 - **Interactive Graph Visualization**: D3.js-powered force-directed graph with physics simulation
-- **Real-Time Pathfinding**: Live progress tracking and result visualization
 - **Dynamic Node Interaction**: Drag-and-drop nodes with intelligent physics
 - **Smart Text Rendering**: Dynamic text truncation based on graph density
 - **Professional Typography**: JetBrains Mono font throughout
-- **Responsive Design**: Works on desktop and mobile devices
+- **Responsive Design**: Works perfectly on desktop and mobile devices
 
 **Navigation:**
 ```
-http://localhost:9020/ui
+http://localhost:9020/       (default landing page)
+http://localhost:9020/ui     (redirects to main UI)
+http://localhost:9020/<any>  (redirects to main UI)
 ```
 
 **Interface Components:**
@@ -369,12 +415,13 @@ http://localhost:9020/ui
 - **Error Handling**: User-friendly error messages and loading states
 
 **Usage:**
-1. Navigate to `/ui` in your browser
-2. Enter Wikipedia page titles in start and end fields
+1. Navigate to `/` in your browser (or any non-API path)
+2. Enter Wikipedia page titles in start and end fields  
 3. Click "Find Path" to initiate pathfinding
-4. Watch real-time graph visualization
-5. Interact with nodes by dragging them
+4. View graph visualization as path is discovered
+5. Interact with nodes by dragging them (mobile-optimized)
 6. Click on path steps to visit Wikipedia pages
+7. State is automatically saved - refresh to resume interrupted searches
 
 **Technical Details:**
 - Uses D3.js v7 for graph visualization
@@ -405,6 +452,9 @@ All endpoints return structured error responses when something goes wrong:
 }
 ```
 
+Note: JSON 404 responses are returned for API-like paths (for example, `/api/...`).
+Requests to non-API paths instead redirect to the main UI (`/`).
+
 **405 Method Not Allowed:**
 ```json
 {
@@ -461,9 +511,11 @@ curl http://localhost:9020/tasks/status/xyz789-abc123-def456
   "status": "IN_PROGRESS",
   "task_id": "xyz789-abc123-def456",
   "progress": {
-    "current_depth": 2,
-    "nodes_explored": 95,
-    "message": "Searching at depth 2..."
+    "current": 10,
+    "total": 100,
+    "status": "Validating pages...",
+    "start_page": "Barack Obama",
+    "end_page": "Computer Science"
   }
 }
 ```
@@ -489,10 +541,10 @@ curl http://localhost:9020/tasks/status/xyz789-abc123-def456
 
 ## Rate Limiting
 
-The API includes basic rate limiting middleware:
-- Default: 100 requests per minute per IP
-- Rate limit headers are included in responses
-- Exceeding limits returns HTTP 429 Too Many Requests
+Basic logging-only rate limiting is present for visibility, but limits are not enforced in this build:
+- Logs each request with a per-IP note; no counters are persisted
+- No `429 Too Many Requests` responses are emitted by default
+- For production-grade limits, plug in a Redis-backed limiter
 
 ## Environment Configuration
 
@@ -569,4 +621,4 @@ For issues and questions:
 - Check the logs: Application logs provide detailed error information
 - Health endpoint: Use `/health` to diagnose system issues
 - Redis connectivity: Ensure Redis is running and accessible
-- Wikipedia API: Check if Wikipedia API is accessible from your network
+- Wikipedia API: Check if Wikipedia API is accessible from your network

API_DOCUMENTATION.md

@@ -39,10 +39,11 @@ The project demonstrates expertise in:
 - **CORS Support**: Cross-origin resource sharing for frontend integration
 
 ### ✅ Interactive Visualization
-- **Web-Based UI**: Modern dark-themed interface for interactive pathfinding
-- **Real-Time Graph Visualization**: D3.js-powered interactive graph with physics simulation
+- **Web-Based UI**: Interactive interface for pathfinding with real-time progress
+- **Graph Visualization**: D3.js-powered interactive graph with physics simulation
+- **Mobile Support**: Touch-optimized interface that works on mobile devices
+- **State Persistence**: Saves progress and resumes interrupted searches
 - **Dynamic Features**: Drag-and-drop nodes, responsive layout, smart text truncation
-- **Professional Design**: Clean typography with JetBrains Mono, opaque text backgrounds
 
 ### ✅ Development Tools
 - **Comprehensive Testing**: Unit and integration tests with 100% pass rate
@@ -68,7 +69,7 @@ The project demonstrates expertise in:
 
 [![pytest](https://img.shields.io/badge/pytest-8.3.3-0A9EDC?style=for-the-badge&logo=pytest&logoColor=white)](https://pytest.org)
 [![Black](https://img.shields.io/badge/Code%20Style-Black-000000?style=for-the-badge&logo=python&logoColor=white)](https://github.com/psf/black)
-[![Coverage](https://img.shields.io/badge/Coverage-81%20Tests%20Passing-success?style=for-the-badge&logo=pytest)](./tests/)
+[![Coverage](https://img.shields.io/badge/Coverage-107%20Tests%20Passing%20(~80%25)-success?style=for-the-badge&logo=pytest)](./tests/)
 [![Marshmallow](https://img.shields.io/badge/Validation-Marshmallow-FF6B6B?style=for-the-badge&logo=python)](https://marshmallow.readthedocs.io/)
 
 ## Project Information
@@ -102,8 +103,8 @@ pip install -r requirements.txt
 ```
 
 The application will be available at:
-- **API**: `http://localhost:9020`
-- **Interactive UI**: `http://localhost:9020/ui`
+- **Interactive UI**: `http://localhost:9020` (default landing page)
+- **API Documentation**: `http://localhost:9020/api`
 
 ### Production Deployment
 ```bash
@@ -121,11 +122,13 @@ export REDIS_URL=redis://localhost:6379/0
 Complete API documentation with examples, request/response schemas, and integration guides is available in [API_DOCUMENTATION.md](./API_DOCUMENTATION.md).
 
 ### Key Endpoints
+- `GET /` - Interactive UI (default landing page)
+- `GET /<any-path>` - All non-API paths redirect to main UI
 - `POST /getPath` - Start pathfinding task (returns task ID for polling)
-- `GET /tasks/status/<task_id>` - Poll task status and retrieve results
+- `GET /tasks/status/<task_id>` - Poll task status with progress updates
 - `POST /explore` - Discover page connections for graph visualization
 - `GET /health` - System health monitoring endpoint
-- `GET /ui` - Interactive web interface for pathfinding visualization
+- `GET /api` - API documentation and information
 
 ## Architecture Highlights
 
@@ -146,17 +149,24 @@ The core pathfinding algorithm demonstrates advanced system design:
 
 ```bash
 # Run comprehensive test suite
-pytest tests/ -v
+pytest -v
 
-# Run with coverage reporting
-pytest tests/ --cov=app --cov-report=html
+# Run with coverage reporting (console + HTML)
+pytest --cov=app --cov-report=term-missing --cov-report=html
 
 # Test specific components
 pytest tests/unit/ -v      # Unit tests
 pytest tests/integration/ -v  # Integration tests
 ```
 
-Current test coverage: **81 tests passing** with comprehensive unit and integration coverage.
+Current test coverage: **107 tests passing** with approximately **80% line coverage** across the `app/` package (see `htmlcov/index.html` after running coverage for a browsable report).
+
+Key areas covered by new tests:
+- Cache and queue infrastructure with Redis client mocking
+- ServiceFactory lifecycle and Celery task configuration helpers
+- Wikipedia client parsing, batching, and request handling with a fake session
+- API middleware decorators (error handling, CORS, rate limiting, size checks)
+- Logging configuration, including file handler setup for non-testing environments
 
 ## Contributors