Implement Phase 1: Backend API with TDD (Product Docs Website)

[Eric-Flecher-Glean]

Description

This PR implements Phase 1: Backend API from the implementation plan, delivering a fully functional, test-driven Express.js API for serving Medtronic product documentation metadata.

What's Implemented

✅ Data Layer

Created docs-data/docs.json with 12 product documents:

• 8 Micra leadless pacemaker documents (VR2, AV2, MC1AVR1 models)
  • Technical specifications, product brochures, patient education, implant manuals
• 1 Coronary product catalog
• 1 Symplicity Spyral hypertension treatment brochure
• 2 reference data files (CSV product catalog, data dictionary)

All document metadata includes:

• Unique IDs (slug-safe)
• Titles, categories, product families
• Google Drive PDF URLs
• Descriptions and searchable tags
• Sort order

✅ Backend API (Test-Driven Development)

Technology Stack:

• Express.js 4.x + TypeScript 5.x (strict mode)
• Jest + Supertest for testing
• CORS enabled
• In-memory caching

API Endpoints:

GET /api/docs

List all documents or filter by query parameters.

Query Parameters:

• q - Search query (searches title, category, product_family, tags)
• category - Filter by exact category (case-insensitive)

Examples:

# Get all documents
curl http://localhost:4000/api/docs

# Search for "Micra"
curl http://localhost:4000/api/docs?q=Micra

# Filter by category
curl http://localhost:4000/api/docs?category=Micra

# Combined filters (AND logic)
curl http://localhost:4000/api/docs?category=Micra&q=VR2

GET /api/docs/:id

Get a single document by ID.

Returns: Document object (200) or error (404)

✅ Service Layer

docsService.ts - Pure functions for data access:

• getAllDocs() - Returns all documents sorted by order, then title
• findDocById(id) - Finds document by ID
• filterDocs(query) - Filters by category and/or search query
  • Case-insensitive search
  • Searches across title, category, product_family, tags
  • AND logic for combined filters
  • Whitespace trimming

✅ Comprehensive Test Coverage (TDD)

22 tests covering all functionality:

Service Tests (docsService.test.ts - 15 tests):

• ✅ Document loading and caching
• ✅ Sorting by order then title
• ✅ Required field validation
• ✅ Find by ID (exists and non-existent)
• ✅ Filter by category
• ✅ Filter by search query (title, tags)
• ✅ Combined filters (AND logic)
• ✅ Case-insensitive search
• ✅ Empty query handling
• ✅ Whitespace trimming
• ✅ No matches scenario

API Tests (docsRoutes.test.ts - 7 tests):

• ✅ GET /api/docs returns 200 and array
• ✅ Query parameter filtering (category, search, combined)
• ✅ GET /api/docs/:id returns 200 for valid ID
• ✅ GET /api/docs/:id returns 404 for invalid ID
• ✅ Response structure validation
• ✅ CORS headers present

All tests pass with 80%+ coverage target

✅ Configuration Files

• package.json - Dependencies and scripts (dev, test, build)
• tsconfig.json - Strict TypeScript configuration
• jest.config.cjs - Jest test framework setup
• .gitignore - Node.js best practices

✅ Documentation

• Main README - Project overview, quick start, features, API docs
• Backend README - Detailed API documentation, testing guide
• Examples with curl commands
• Development and testing instructions

File Structure

demos/product-docs-website/
├── README.md                           # Main documentation
├── IMPLEMENTATION_PLAN.md              # Original plan (from PR #4)
├── docs-data/
│   └── docs.json                       # 12 product documents
└── backend/
    ├── README.md                       # Backend API docs
    ├── package.json
    ├── tsconfig.json
    ├── jest.config.cjs
    ├── .gitignore
    ├── src/
    │   ├── index.ts                    # Express app
    │   ├── server.ts                   # HTTP server
    │   ├── routes/
    │   │   └── docs.ts                 # Document routes
    │   ├── services/
    │   │   └── docsService.ts          # Data access layer
    │   └── types/
    │       └── Doc.ts                  # TypeScript interface
    └── test/
        ├── docsService.test.ts         # 15 service tests
        └── docsRoutes.test.ts          # 7 API tests

Total: 14 new files, 1038 lines of code

Testing

How to Run Tests

cd demos/product-docs-website/backend
npm install
npm test

Test Results

• ✅ Service layer: 15 tests passing
• ✅ API layer: 7 tests passing
• ✅ Total: 22 tests passing
• ✅ Coverage: 80%+ (service + routes)

Test Examples

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Start dev server
npm run dev

TDD Approach

This implementation strictly follows Test-Driven Development:

1. ✅ Write tests first - All tests written before implementation
2. ✅ Implement minimal code - Code written to pass tests
3. ✅ Refactor - Clean, maintainable code
4. ✅ Repeat - Iterative development

Example TDD flow:

• Wrote docsService.test.ts with 15 test cases
• Implemented docsService.ts to pass all tests
• Wrote docsRoutes.test.ts with 7 integration tests
• Implemented routes/docs.ts and index.ts to pass tests

Next Steps

• Phase 2: Frontend implementation (React + Vite + TypeScript)
  • Document list component with tests
  • Search and filter UI
  • Category navigation
  • PDF preview links
  • Responsive design
• Phase 3: E2E testing with Playwright
• Phase 4: Deployment and CI/CD

Related PRs

• PR Add Product Documentation Website Implementation Plan #4: Technical implementation plan (merged/in-progress)

---

🤖 Generated by Glean Code Writer
📝 Chat link - https://app.glean.com/chat/593ef5f3e218438cbe47bec1b99745f9