🏗️ Architecture: How to make the API viewer/explorer reusable across all 4 Go...

Date: 2026-02-09
Time: 22:17:05 UTC
Session: gspace1-101.4
Agent: backend
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How to make the API viewer/explorer reusable across all 4 GoGrab backends?

Task: Deploy API viewer library to all 4 backends

🎯 Decision Made

Chosen:

Created dedicated @libs-api/api-viewer NX library with modular structure, deployed to all 4 backends with identical patterns

Options Considered:

1. Keep code in backend-core and copy/paste per backend
2. Create @libs-api/api-viewer dedicated library
3. Create a NestJS dynamic module that auto-registers routes

💭 Reasoning

Extracted ~690 lines of service-identity code from @libs-api/backend-core into a new @libs-api/api-viewer library with clean separation: types/ (viewer.types.ts), utils/ (content-negotiation, route-discovery, version-detect, service-url), renderers/ (identity, health, explorer with search+filters), shared/ (css split into 10 logical groups, branding with inline GoGrab SVG, helpers). Each backend follows the same integration pattern: (1) AppService provides identity/health/routeGroups using api-viewer types, (2) AppController with soft-auth via @Public()+JwtAuthGuard for content-negotiated responses, (3) SystemController at /system/explorer with admin role check, (4) main.ts calls discoverRoutes() after listen and registers a root redirect handler. Backend-core retains a deprecated re-export for backward compatibility.

📁 Files Involved

• libs/libs-api/api-viewer/src/index.ts
• libs/libs-api/api-viewer/src/lib/types/viewer.types.ts
• libs/libs-api/api-viewer/src/lib/renderers/explorer.renderer.ts
• libs/libs-api/api-viewer/src/lib/renderers/shared/css.ts
• libs/libs-api/api-viewer/src/lib/renderers/shared/branding.ts
• libs/libs-api/api-viewer/src/lib/utils/service-url.ts
• apis/backend-api/src/app/app.service.ts
• apis/backend-ai-api/src/app/app.service.ts
• apis/backend-docs-api/src/app/app.service.ts
• apis/backend-vitto-api/src/app/app.service.ts

🔗 Related

• Decision ID: dev_1770675421546_rofuehu
• Session: 101
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation