Local Testing Guide

Complete guide for testing backend-docs-api locally

Backend Docs API - Local Testing Guide

Step-by-step guide for testing the complete local development flow with real-time sync.

Prerequisites

  1. MongoDB Atlas test-modules cluster configured
  2. .env.local file with all required variables
  3. All dependencies installed: yarn install

Step 1: Configure Environment

Ensure .env.local contains:

# Docs API Configuration
DOCS_API_PORT=3002
MONGODB_CONNECTION_STRING_TEST_MODULES=mongodb+srv://...

# Shared Authentication
JWT_SECRET=<YOUR_JWT_SECRET_FROM_ENV_LOCAL>
SYSTEM_TOKEN=<your-system-token>

# Cloud Sync
ENABLE_CLOUD_SYNC=true
DOCS_API_URL=http://localhost:3002/docs-api

Step 2: Build the Application

# Build backend-docs-api
nx build backend-docs-api

Expected output:

✅ Build completed successfully
📦 Output: dist/apis/backend-docs-api/

Step 3: Start the API Server

# Start backend-docs-api
yarn serve:backend-docs

Expected console output:

📚 GoGrab Backend Docs API READY on port 3002

📡 Server:      http://localhost:3002/docs-api
🗄️  Database:    docs-database (test-modules cluster)
📄 Collections:  doc-files, doc-projects, analytics
🔥 Docs Sync Gateway initialized
📡 Listening on namespace: /docs-sync
✅ Watching doc-files collection for changes
✅ Watching doc-projects collection for changes

Step 4: Test Health Check

curl http://localhost:3002/docs-api/health

Expected response:

{
  "status": "ok",
  "timestamp": "2025-12-21T...",
  "service": "backend-docs-api",
  "database": "docs-database"
}

Step 5: Initial Bulk Sync

Upload all /docs files to MongoDB:

yarn docs:sync

Expected output:

☁️  Starting bulk sync to cloud...
📁 Docs path: /Users/.../editor/docs
🌐 API URL: http://localhost:3002/docs-api

🔍 Scanning documentation files...
📊 Found 450 markdown files

📤 Uploading batch 1/9 (50 files)...
✅ Batch 1 uploaded: 50 created, 0 updated
...

╔════════════════════════════════════════╗
║     ☁️  Bulk Sync Complete           ║
╚════════════════════════════════════════╝

✅ Uploaded: 450 files
❌ Failed:   0 files
⏱️  Duration: 12.5s

Step 6: Start File Watcher

In a new terminal:

yarn docs:watch

Expected output:

👁️ Starting documentation file watcher...
📁 Watching: /Users/.../editor/docs
✅ File watchers started successfully
🎯 Watching for:
   - .md and .mdc file changes
   - Folder renames and structural changes
   - Directory additions and deletions
   - Config file changes
💡 Press Ctrl+C to stop watching

Step 7: Test Real-Time Sync

Test File Creation

  1. Create a new file: docs/english/test-sync.md
---
title: Test Sync
description: Testing real-time sync
---

# Test Sync

This file tests real-time synchronization.
  1. Watch the file watcher console:
📝 File changed: english/test-sync.md (change)
🔄 Regenerating manifest and folders config...
☁️  Syncing 1 file(s) to cloud...
☁️  Synced to cloud: english/test-sync.md (upsert)
✅ Regeneration completed successfully
  1. Verify in MongoDB:
# Query the API
curl http://localhost:3002/docs-api/sync/files/english/test-sync.md

Test File Update

  1. Edit docs/english/test-sync.md
  2. Watch console for sync confirmation
  3. Verify updated content in MongoDB

Test File Deletion

  1. Delete docs/english/test-sync.md
  2. Watch console:
🗑️  Structure changed (deleted): english/test-sync.md (rename)
☁️  Synced to cloud: english/test-sync.md (delete)
  1. Verify file removed from MongoDB

Step 8: Start docs-angular

In a new terminal:

yarn serve:docs

Expected output:

📚 docs-angular running on http://localhost:5010
✅ Connected to backend-docs-api

Step 9: Test Admin Features

  1. Navigate to: http://localhost:5010/admin
  2. Enter admin password (default: admin123)
  3. Test admin features:

Test Watch Process Control

Test Manual Scan

Test Cloud File Manager

Step 10: Test Analytics

  1. Navigate to some documentation pages
  2. Perform some searches
  3. Go to /admin/analytics
  4. Verify analytics data is displayed

Test Analytics Persistence

# Check MongoDB for analytics data
curl http://localhost:3002/docs-api/analytics/summary

Expected response:

{
  "totalPageViews": 15,
  "totalSearches": 5,
  "avgPageLoadTime": 250,
  "avgSearchResponseTime": 100
}

Step 11: Test WebSocket Real-Time Updates

In Browser Console

// Connect to WebSocket
const socket = io('http://localhost:3002/docs-sync');

socket.on('connect', () => {
  console.log('✅ Connected to docs-sync');
});

socket.on('file-change', (data) => {
  console.log('📡 File changed:', data);
});

socket.on('manifest-updated', (data) => {
  console.log('📡 Manifest updated:', data);
});

Test Real-Time Broadcast

  1. Edit a file in /docs
  2. Watch browser console for file-change event
  3. Verify event contains correct file data

Complete Test Checklist

Common Issues

"Connection refused" Error

Problem: Can't connect to backend-docs-api

Solution:

# Check if API is running
curl http://localhost:3002/docs-api/health

# If not, start it
yarn serve:backend-docs

"Unauthorized" Error

Problem: JWT authentication failing

Solution:

  1. Verify JWT_SECRET matches across all APIs
  2. Check SYSTEM_TOKEN is set in .env.local
  3. Ensure token is being sent in Authorization header

Files Not Syncing

Problem: File changes not appearing in MongoDB

Solution:

  1. Check ENABLE_CLOUD_SYNC=true
  2. Verify SYSTEM_TOKEN is correct
  3. Check file watcher is running
  4. Review API logs for errors

MongoDB Connection Error

Problem: Can't connect to MongoDB

Solution:

  1. Verify MONGODB_CONNECTION_STRING_TEST_MODULES is correct
  2. Check MongoDB Atlas network access (whitelist your IP)
  3. Ensure database user has read/write permissions
  4. Test connection string with MongoDB Compass

Performance Benchmarks

Expected Timings

Operation Expected Time
API Startup 2-3 seconds
Health Check <100ms
Single File Sync <500ms
Bulk Sync (450 files) 10-15 seconds
File Read <200ms
Analytics Query <300ms
WebSocket Connect <100ms

Next Steps

After successful local testing:

  1. Deploy to Railway
  2. Update frontend production environment
  3. Build static docs-angular
  4. Deploy to gograb.space/docs

Related Documentation