System Architecture

How DocHub serves three tiers of documentation from a single Express application

Component Overview

globe
Browser
HTTPS request
:443
shield
nginx
SSL + reverse proxy
:3002
server
Express
DocHub app
:5433
database
PostgreSQL
Sessions
Express App Internals
MarkdownService — Parse & render .md files
ManifestService — Generate JSON manifests
TemplateService — HTML layout & styling
Passport — Google OAuth authentication
Content Directory
content/ — Markdown files
_overviews/ — HTML overviews
_project.yaml — Metadata

Request Flow

1
Browser requests https://docs.ipnoelp.com/docs/dochub/architecture/overview
2
nginx terminates SSL, sets proxy headers (X-Real-IP, X-Forwarded-Proto), forwards to localhost:3002
3
Express middleware runs: Helmet (security) → Morgan (logging) → Session (PG store) → Passport (auth check)
4
Auth check — Is session valid? If not, redirect to /auth/login for Google OAuth
5
Docs route extracts path: project=dochub, subproject=architecture, page=overview
6
MarkdownService reads content/dochub/architecture/overview.md, parses frontmatter (gray-matter), renders HTML (markdown-it + highlight.js)
7
TemplateService wraps content in layout with sidebar navigation, breadcrumbs, and table of contents
8
Complete HTML page returned to browser with inline CSS and syntax-highlighted code blocks

Three-Tier Documentation Model

Tier 1
/overview/
Visual HTML pages with flow diagrams, architecture maps, and system relationships. Self-contained, no template wrapping.
Tier 2
/docs/
Structured markdown rendered as HTML with sidebar navigation, breadcrumbs, TOC, and code highlighting.
Tier 3
/api/
JSON manifests for project discovery + raw markdown endpoints for Claude CLI consumption.

Port Allocation

All services share a single DigitalOcean droplet at 178.128.183.166

Service Port Domain Process Manager
CMS Frontend 3000 cms.ipnoelp.com start-cms.sh
CMS Backend 3001 cms.ipnoelp.com/api start-cms.sh
DocHub 3002 docs.ipnoelp.com PM2
PostgreSQL 5433 localhost only Docker

Technology Stack

Runtime & Framework
Express.js — HTTP server and routing
TypeScript — Compiled to dist/
Node.js 20 — LTS runtime
Content Processing
markdown-it — Markdown to HTML
gray-matter — YAML frontmatter
highlight.js — Code syntax highlighting
Authentication
Passport.js — Google OAuth 2.0
connect-pg-simple — PG session store
Shared cookies — .ipnoelp.com domain
Infrastructure
nginx — Reverse proxy + SSL
PM2 — Process management
Let's Encrypt — SSL certificates
Drill down: Architecture Details · Service Layer · Production Deployment · Back to Hub