Knowledge Base App

App: apps/knowledgebase · Port: :3004 · Audience: Internal Leadmetrics team

The Knowledge Base is an internal documentation site that renders the docs/ folder as a searchable, navigable web app. It is built with Nextra v4 (Next.js App Router) and serves all 289 markdown documents from the monorepo’s docs/ directory.

Status

Layer	Status
Nextra v4 docs rendering	[Live]
Navigation with `_meta.ts` sections	[Live]
Built-in full-text search (Ctrl+K)	[Live]
Right-side TOC per page	[Live]
Google OAuth login gate	[To Build]

Tech Stack

Concern	Choice
Framework	Next.js 15 App Router
Docs engine	Nextra v4 + `nextra-theme-docs`
Content source	Windows junction `content/` → `../../docs/`
Auth (planned)	`next-auth@beta` — Google provider, JWT sessions
Port	3004
Package name	`@leadmetrics/knowledgebase`

Content Source

The app does not copy the docs — it reads them live via a Windows directory junction:


apps/knowledgebase/content/  →  (junction)  →  docs/

All 283 markdown files are served directly. Editing a file in docs/ is immediately reflected in dev mode (after hot reload).

Warning: Git does not preserve Windows junctions. After a fresh clone or git clean, content/ becomes a plain empty directory and the site renders blank. Recreate it with:
Remove-Item "apps\knowledgebase\content" -Recurse -Force
New-Item -ItemType Junction -Path "apps\knowledgebase\content" -Target (Resolve-Path "docs")

Top-level navigation is controlled by docs/_meta.ts. This file defines:

Display labels for each page/folder
Section separators (Overview, Getting Started, Applications, AI Agents, etc.)
Hidden pages (missing-incomplete-features/, test-scenarios/, open-questions/)

Subdirectory navigation uses Nextra’s auto-discovery (labels derived from filenames). Per-directory _meta.ts files can be added to clean up sub-page labels further.

Sidebar sections

Section	Contents
Overview	Architecture, Workflow Model, Tech Stack, Project Plan
Getting Started	Onboarding, Self-Signup, Multi-Tenancy, Security
Applications	Apps & Portals
AI Agents	Agents, Adapters, Agent Chat
Content & Campaigns	Activity Types, Content Toolkit, Campaigns
CRM	CRM & Pipeline, Contacts
Channels & Integrations	Channels, Providers, MCP
Platform Services	Database, Servers, API, Features, Credits, Insights, HITL
UI & Experience	UI Components, Chat, Code Reviews
Infrastructure	Infrastructure, Performance, Scalability, LLM Providers
Reference	Testing, Examples

Dev Notes

First compile is slow (~3.5 min) because Nextra builds a webpack module context for all 289 files. Subsequent page requests are fast (1–2s).
The root / catches the optional [[...mdxPath]] route and falls back to loading INDEX.md explicitly (since the file is named INDEX.md not index.md).
react and react-dom are pinned to 19.2.4 (exact) to match nextra-theme-docs peer dep — do not loosen this constraint.
_meta.ts keys must not include the file extension ("architecture" not "architecture.md").

Adding Google Auth

Auth is already designed. When ready:

Copy next-auth@beta, src/auth.ts, src/middleware.ts, src/app/(auth)/login/page.tsx, src/app/api/auth/[...nextauth]/route.ts from the design in this session.
Add to .env.local: AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET, AUTH_SECRET.
Create an OAuth 2.0 Client in Google Cloud Console; set redirect URI to https://your-domain/api/auth/callback/google.

Running Locally


cd apps/knowledgebase
pnpm dev          # starts on http://localhost:3004