Backend Docs API

Documentation management NestJS backend with real-time synchronization to MongoDB.

Overview

The Backend Docs API is a NestJS application that manages documentation files from the /docs folder, syncing them to MongoDB (test-modules cluster) with real-time updates via WebSocket and MongoDB Change Streams.

Key Features

• Real-Time Sync: File changes automatically sync to MongoDB
• Shared Authentication: Uses same JWT as backend-api and backend-ai-api
• WebSocket Broadcasting: Live updates to all connected clients
• MongoDB Change Streams: Real-time database notifications
• Analytics Persistence: Track page views and searches with 7-day TTL
• Admin API: Manage watch processes and trigger scans

Architecture

/docs folder (local)
    ↓
watch-docs-changes.js (file watcher)
    ↓
backend-docs-api :3002
    ↓
MongoDB (test-modules cluster)
    ↓
docs-angular (frontend)

Quick Start

Local Development

# Start the docs API
yarn serve:backend-docs

# Or start all backends
yarn dev:all-backends

Initial Bulk Sync

# Upload all /docs files to MongoDB
yarn docs:sync

API Endpoints

Public Endpoints (No Auth)

• GET /docs-api/sync/files - List all files
• GET /docs-api/sync/files/:path - Get file by path
• GET /docs-api/sync/manifest - Get manifest
• GET /docs-api/sync/projects - List projects
• GET /docs-api/sync/search?q= - Search docs
• GET /docs-api/admin/docs/folders-config - Folders/projects config
• GET /docs-api/sessions/:token - Resolve view session (shareable links)
• POST /docs-api/analytics/page-views - Track page view
• POST /docs-api/analytics/search-events - Track search

Unauthenticated access: See public-access.md for the full design and link-based sharing.

Protected Endpoints (JWT Required)

• POST /docs-api/sync/files - Create/update file
• DELETE /docs-api/sync/files/:path - Delete file
• POST /docs-api/sync/bulk - Bulk sync
• POST /docs-api/admin/docs/start-watch - Start watch
• POST /docs-api/admin/docs/trigger-scan - Manual scan
• GET /docs-api/analytics/summary - Analytics summary

Configuration

Environment Variables

# Local port
DOCS_API_PORT=3002

# MongoDB connection (test-modules cluster)
MONGODB_CONNECTION_STRING_TEST_MODULES=mongodb+srv://...

# Shared authentication
JWT_SECRET=<same as backend-api>
SYSTEM_TOKEN=<for internal services>

# CORS origins
ALLOWED_ORIGINS=http://localhost:5010,https://gograb.space

File Watcher Configuration

# Enable/disable cloud sync
ENABLE_CLOUD_SYNC=true

# API URL
DOCS_API_URL=http://localhost:3002/docs-api

# System token for authentication
SYSTEM_TOKEN=<your-token>

Railway Deployment

Deploy Script

./deployment/deploy-docs-api.sh

Required Railway Variables

• NODE_ENV=production
• JWT_SECRET (same as other APIs)
• SYSTEM_TOKEN (same as other APIs)
• MONGODB_CONNECTION_STRING_TEST_MODULES
• ALLOWED_ORIGINS

Health Check

curl https://your-docs-api.railway.app/docs-api/health

Integration with docs-angular

The frontend uses DocsApiService for all API communication:

import { DocsApiService } from './services/docs-api.service';

// In your component/service
constructor(private docsApi: DocsApiService) {}

// Get files
const files = await this.docsApi.getAllFiles();

// Track analytics
await this.docsApi.trackPageView({ path, project, language });

// Admin operations
await this.docsApi.startWatch();

Real-Time Updates

WebSocket Connection

import { io } from 'socket.io-client';

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

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

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

MongoDB Collections

doc-files

Stores all documentation files with content and metadata.

{
  path: "english/GoGrab-Space/README.md",
  content: "# GoGrab Space\n\n...",
  metadata: {
    title: "GoGrab Space",
    language: "en",
    project: "GoGrab-Space"
  },
  contentHash: "sha256...",
  version: 1
}

doc-projects

Stores project configurations.

{
  name: "GoGrab-Space",
  displayName: "GoGrab Space",
  isRoot: true,
  config: {
    search: { ... },
    navigation: { ... }
  }
}

page-views

Analytics data with 7-day TTL.

{
  path: "/GoGrab-Space/overview",
  project: "GoGrab-Space",
  language: "en",
  duration: 45000,
  createdAt: Date  // Auto-deleted after 7 days
}

search-events

Search analytics with 7-day TTL.

{
  query: "widget system",
  resultsCount: 15,
  project: "GoGrab-Space",
  createdAt: Date  // Auto-deleted after 7 days
}

Development

Build

nx build backend-docs-api

Test

nx test backend-docs-api

Serve

nx serve backend-docs-api

Troubleshooting

Connection Issues

If the frontend can't connect to the API:

1. Check API is running: curl http://localhost:3002/docs-api/health
2. Verify CORS origins in .env.local
3. Check JWT_SECRET matches across all APIs

Sync Issues

If files aren't syncing:

1. Check ENABLE_CLOUD_SYNC=true in environment
2. Verify SYSTEM_TOKEN is set
3. Check API logs for errors
4. Run manual sync: yarn docs:sync

Railway Deployment Issues

1. Verify environment variables in Railway dashboard
2. Check health check endpoint is responding
3. Review Railway logs for errors
4. Ensure MongoDB connection string is correct

Related Documentation

• Docs Angular App
• Railway Deployment Guide
• Backend API
• Backend AI API