Architecture: How to organize the API viewer/explorer code for reuse acros...

Documentation for Sessions

🏗️ Architecture: How to organize the API viewer/explorer code for reuse acros...

Date: 2026-02-09
Time: 20:58:00 UTC
Session: gspace1-101.3
Agent: backend
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How to organize the API viewer/explorer code for reuse across all 4 backends?

Task: Extract API viewer into dedicated NX library with search, filters, branding

🎯 Decision Made

Chosen:

Extract from backend-core into dedicated @libs-api/api-viewer library with modular structure

Options Considered:

Keep in backend-core and grow it
Create @libs-api/api-viewer dedicated library
Create a NestJS module instead of pure utils

💭 Reasoning

The service-identity module (~690 lines) was embedded inside backend-core alongside unrelated schemas, configs, and services. This violated single responsibility and made the viewer features harder to enhance independently. Created @libs-api/api-viewer with: types/viewer.types.ts, utils/ (content-negotiation, route-discovery, version-detect, service-url), renderers/ (identity, health, explorer with search+filters), and shared/ (css split into logical groups, branding with inline GoGrab SVG, helpers). Maintained backward compatibility via deprecation re-export in backend-core. Added resolveServiceUrl() utility to fix the docs URL environment bug. All 3 projects (api-viewer, backend-core, backend-api) build successfully.

📁 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/utils/route-discovery.ts
libs/libs-api/api-viewer/src/lib/utils/service-url.ts
libs/libs-api/api-viewer/src/lib/renderers/explorer.renderer.ts
libs/libs-api/api-viewer/src/lib/renderers/identity.renderer.ts
libs/libs-api/api-viewer/src/lib/renderers/health.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/renderers/shared/helpers.ts
apis/backend-api/src/app/app.service.ts
apis/backend-api/src/app/app.controller.ts
apis/backend-api/src/app/system/system.controller.ts
apis/backend-api/src/main.ts
libs/libs-api/backend-core/src/lib/utils/service-identity.utils.ts

🔗 Related

Decision ID: dev_1770670676567_dw6h7xj
Session: 101
Workspace: gspace1

Auto-generated by MCP Smart Consolidation