Refactor documentation and code for improved clarity and consistency

- Updated setup instructions in `index.md` to include Docker options and clarify manual setup steps.
- Simplified method signatures in various service classes for better readability.
- Consolidated test cases in `unit.md` and `integration.md` to enhance maintainability.
- Improved performance testing scripts for better clarity and efficiency.
- Updated database setup instructions in `quickstart.md` to reflect changes in database configuration.
- Enhanced error handling and logging in service methods across multiple files.

Author: Thavarshan

docs/.vitepress/theme/index.ts

@@ -30,30 +30,20 @@ export default {
           // Function to render mermaid diagrams
           const renderMermaidDiagrams = async () => {
             // Try multiple selectors to find mermaid code blocks
-            let mermaidElements = document.querySelectorAll(
-              'pre code.language-mermaid'
-            );
+            let mermaidElements = document.querySelectorAll('pre code.language-mermaid');
 
             // If not found, try alternative selectors
             if (mermaidElements.length === 0) {
-              mermaidElements = document.querySelectorAll(
-                'code.language-mermaid'
-              );
+              mermaidElements = document.querySelectorAll('code.language-mermaid');
             }
             if (mermaidElements.length === 0) {
-              mermaidElements = document.querySelectorAll(
-                'pre[class*="language-mermaid"] code'
-              );
+              mermaidElements = document.querySelectorAll('pre[class*="language-mermaid"] code');
             }
             if (mermaidElements.length === 0) {
-              mermaidElements = document.querySelectorAll(
-                '[class*="language-mermaid"]'
-              );
+              mermaidElements = document.querySelectorAll('[class*="language-mermaid"]');
             }
 
-            console.log(
-              `Found ${mermaidElements.length} mermaid diagrams to render`
-            );
+            console.log(`Found ${mermaidElements.length} mermaid diagrams to render`);
 
             for (let i = 0; i < mermaidElements.length; i++) {
               const element = mermaidElements[i] as HTMLElement;

docs/api/analytics.md

@@ -38,7 +38,7 @@ graph TD
 
 Get a comprehensive dashboard view of your search analytics.
 
-**Endpoint**: `GET /api/analytics/dashboard`
+**Endpoint**: `GET /api/v1/analytics/dashboard`
 
 **Query Parameters**:
 
@@ -136,7 +136,7 @@ Authorization: Bearer <YOUR_API_KEY>
 
 Get detailed search trend analysis over time.
 
-**Endpoint**: `GET /api/analytics/trends`
+**Endpoint**: `GET /api/v1/analytics/trends`
 
 **Query Parameters**:
 
@@ -216,7 +216,7 @@ Get detailed search trend analysis over time.
 
 Get detailed performance analytics including response times, error rates, and resource utilization.
 
-**Endpoint**: `GET /api/analytics/performance`
+**Endpoint**: `GET /api/v1/analytics/performance`
 
 **Query Parameters**:
 
@@ -242,7 +242,7 @@ Get detailed performance analytics including response times, error rates, and re
       },
       "endpoints": [
         {
-          "endpoint": "/api/search",
+          "endpoint": "/api/v1/search",
           "totalRequests": 1250,
           "averageResponseTime": 267,
           "successRate": 0.981,
@@ -302,7 +302,7 @@ Get detailed performance analytics including response times, error rates, and re
 
 Get the most popular search queries with detailed analytics.
 
-**Endpoint**: `GET /api/analytics/popular-queries`
+**Endpoint**: `GET /api/v1/analytics/popular-queries`
 
 **Query Parameters**:
 
@@ -373,7 +373,7 @@ Get the most popular search queries with detailed analytics.
 
 Get AI-powered insights and recommendations based on your search patterns.
 
-**Endpoint**: `GET /api/analytics/insights`
+**Endpoint**: `GET /api/v1/analytics/insights`
 
 **Query Parameters**:
 
@@ -481,7 +481,7 @@ Get AI-powered insights and recommendations based on your search patterns.
 
 Get comprehensive system-wide analytics and health metrics.
 
-**Endpoint**: `GET /api/analytics/overview`
+**Endpoint**: `GET /api/v1/analytics/overview`
 
 **Response**:
 
@@ -545,7 +545,7 @@ Get comprehensive system-wide analytics and health metrics.
 
 Get detailed user activity and engagement metrics.
 
-**Endpoint**: `GET /api/analytics/user-activity`
+**Endpoint**: `GET /api/v1/analytics/user-activity`
 
 **Query Parameters**:
 
@@ -620,7 +620,7 @@ Get detailed user activity and engagement metrics.
 
 Define custom metrics for tracking specific KPIs.
 
-**Endpoint**: `POST /api/analytics/custom-metrics`
+**Endpoint**: `POST /api/v1/analytics/custom-metrics`
 
 **Request Body**:
 
@@ -646,7 +646,7 @@ Define custom metrics for tracking specific KPIs.
 
 Export analytics data in various formats for external analysis.
 
-**Endpoint**: `GET /api/analytics/export`
+**Endpoint**: `GET /api/v1/analytics/export`
 
 **Query Parameters**:
 
@@ -677,7 +677,7 @@ class Altus4Analytics {
     if (databases) params.append('databases', databases.join(','));
 
     const response = await fetch(
-      `${this.baseUrl}/api/analytics/dashboard?${params}`,
+      `${this.baseUrl}/api/v1/analytics/dashboard?${params}`,
       { headers: this.headers }
     );
 
@@ -692,7 +692,7 @@ class Altus4Analytics {
     });
 
     const response = await fetch(
-      `${this.baseUrl}/api/analytics/trends?${params}`,
+      `${this.baseUrl}/api/v1/analytics/trends?${params}`,
       { headers: this.headers }
     );
 
@@ -704,7 +704,7 @@ class Altus4Analytics {
     if (category) params.append('category', category);
 
     const response = await fetch(
-      `${this.baseUrl}/api/analytics/popular-queries?${params}`,
+      `${this.baseUrl}/api/v1/analytics/popular-queries?${params}`,
       { headers: this.headers }
     );
 
@@ -715,7 +715,7 @@ class Altus4Analytics {
     const params = new URLSearchParams({ type });
 
     const response = await fetch(
-      `${this.baseUrl}/api/analytics/insights?${params}`,
+      `${this.baseUrl}/api/v1/analytics/insights?${params}`,
       { headers: this.headers }
     );
 
@@ -730,7 +730,7 @@ class Altus4Analytics {
     });
 
     const response = await fetch(
-      `${this.baseUrl}/api/analytics/performance?${params}`,
+      `${this.baseUrl}/api/v1/analytics/performance?${params}`,
       { headers: this.headers }
     );
 
@@ -781,23 +781,23 @@ class Altus4AnalyticsDashboard:
 
     def get_dashboard_data(self, period='week'):
         response = requests.get(
-            f'{self.base_url}/api/analytics/dashboard',
+            f'{self.base_url}/api/v1/analytics/dashboard',
             headers=self.headers,
             params={'period': period}
         )
         return response.json()['data']['dashboard']
 
     def get_search_trends(self, period='month', limit=100):
         response = requests.get(
-            f'{self.base_url}/api/analytics/trends',
+            f'{self.base_url}/api/v1/analytics/trends',
             headers=self.headers,
             params={'period': period, 'limit': limit}
         )
         return response.json()['data']['trends']
 
     def get_performance_metrics(self, period='day'):
         response = requests.get(
-            f'{self.base_url}/api/analytics/performance',
+            f'{self.base_url}/api/v1/analytics/performance',
             headers=self.headers,
             params={'period': period, 'breakdown': 'endpoint,database'}
         )

docs/api/authentication.md

@@ -47,7 +47,7 @@ The format includes:
 
 Register a new user account to begin the authentication process.
 
-**Endpoint**: `POST /api/auth/register`
+**Endpoint**: `POST /api/v1/auth/register`
 
 **Headers**:
 
@@ -86,7 +86,7 @@ Content-Type: application/json
 **cURL Example**:
 
 ```bash
-curl -X POST https://api.altus4.dev/api/auth/register \
+curl -X POST https://api.altus4.dev/api/v1/auth/register \
   -H "Content-Type: application/json" \
   -d '{
     "email": "user@example.com",
@@ -99,7 +99,7 @@ curl -X POST https://api.altus4.dev/api/auth/register \
 
 Login to receive a JWT token for API key creation. This JWT token should only be used to create your initial API key.
 
-**Endpoint**: `POST /api/auth/login`
+**Endpoint**: `POST /api/v1/auth/login`
 
 **Headers**:
 
@@ -139,7 +139,7 @@ Content-Type: application/json
 **cURL Example**:
 
 ```bash
-curl -X POST https://api.altus4.dev/api/auth/login \
+curl -X POST https://api.altus4.dev/api/v1/auth/login \
   -H "Content-Type: application/json" \
   -d '{
     "email": "user@example.com",
@@ -151,7 +151,7 @@ curl -X POST https://api.altus4.dev/api/auth/login \
 
 Create your first API key using the JWT token from login. This is a one-time setup process.
 
-**Endpoint**: `POST /api/management/setup`
+**Endpoint**: `POST /api/v1/management/setup`
 
 **Headers**:
 
@@ -181,7 +181,7 @@ Authorization: Bearer <JWT_TOKEN_FROM_LOGIN>
 **cURL Example**:
 
 ```bash
-curl -X POST https://api.altus4.dev/api/management/setup \
+curl -X POST https://api.altus4.dev/api/v1/management/setup \
   -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
 ```
 
@@ -193,7 +193,7 @@ Once you have your initial API key, use it to manage additional keys and your ac
 
 Create additional API keys for different environments or use cases.
 
-**Endpoint**: `POST /api/keys`
+**Endpoint**: `POST /api/v1/keys`
 
 **Headers**:
 
@@ -240,7 +240,7 @@ Content-Type: application/json
 
 Retrieve all API keys associated with your account.
 
-**Endpoint**: `GET /api/keys`
+**Endpoint**: `GET /api/v1/keys`
 
 **Headers**:
 
@@ -275,7 +275,7 @@ Authorization: Bearer <YOUR_API_KEY>
 
 Update an existing API key's name, tier, or permissions.
 
-**Endpoint**: `PUT /api/keys/:keyId`
+**Endpoint**: `PUT /api/v1/keys/:keyId`
 
 **Headers**:
 
@@ -298,7 +298,7 @@ Content-Type: application/json
 
 Permanently revoke an API key. This action cannot be undone.
 
-**Endpoint**: `DELETE /api/keys/:keyId`
+**Endpoint**: `DELETE /api/v1/keys/:keyId`
 
 **Headers**:
 
@@ -322,7 +322,7 @@ Authorization: Bearer <YOUR_API_KEY>
 
 Generate a new secret for an existing API key while maintaining the same ID and settings.
 
-**Endpoint**: `POST /api/keys/:keyId/regenerate`
+**Endpoint**: `POST /api/v1/keys/:keyId/regenerate`
 
 **Headers**:
 
@@ -351,7 +351,7 @@ Authorization: Bearer <YOUR_API_KEY>
 
 Get detailed usage statistics for a specific API key.
 
-**Endpoint**: `GET /api/keys/:keyId/usage`
+**Endpoint**: `GET /api/v1/keys/:keyId/usage`
 
 **Query Parameters**:
 
@@ -378,7 +378,7 @@ Authorization: Bearer <YOUR_API_KEY>
       "averageResponseTime": 245,
       "topEndpoints": [
         {
-          "endpoint": "/api/search",
+          "endpoint": "/api/v1/search",
           "requests": 800,
           "averageResponseTime": 280
         }
@@ -408,7 +408,7 @@ Authorization: Bearer altus4_sk_live_abc123def456...
 ```javascript
 const apiKey = 'altus4_sk_live_abc123def456...';
 
-const response = await fetch('https://api.altus4.dev/api/search', {
+const response = await fetch('https://api.altus4.dev/api/v1/search', {
   method: 'POST',
   headers: {
     Authorization: `Bearer ${apiKey}`,
@@ -432,7 +432,7 @@ import requests
 api_key = 'altus4_sk_live_abc123def456...'
 
 response = requests.post(
-    'https://api.altus4.dev/api/search',
+    'https://api.altus4.dev/api/v1/search',
     headers={
         'Authorization': f'Bearer {api_key}',
         'Content-Type': 'application/json'
@@ -578,4 +578,60 @@ Expected response:
 
 ---
 
+## Testing Authentication
+
+For local development and testing, you can use these pre-configured credentials:
+
+### Test User Credentials
+
+```json
+{
+  "email": "postman@example.com",
+  "password": "postman123"
+}
+```
+
+### Complete Testing Flow
+
+1. **Login to get JWT token**:
+
+```bash
+curl -X POST http://localhost:3000/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "postman@example.com",
+    "password": "postman123"
+  }'
+```
+
+2. **Create API key using JWT**:
+
+```bash
+curl -X POST http://localhost:3000/api/v1/management/setup \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
+  -d '{
+    "name": "Test API Key"
+  }'
+```
+
+3. **Use API key for search**:
+
+```bash
+curl -X POST http://localhost:3000/api/v1/search \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -d '{
+    "query": "test search",
+    "databases": [],
+    "limit": 5
+  }'
+```
+
+### Postman Collection
+
+A complete Postman collection with all authentication flows is available in the `/examples` directory.
+
+---
+
 **Next Steps**: [Search Operations](./search.md) | [Database Management](./database.md)