Content Structure

All documentation lives in the content/ directory. Content is organized into two categories: visual overview HTML pages (Tier 1) and structured markdown documentation (Tier 2). Markdown follows a three-level hierarchy: project, subproject, page.

Directory Layout

content/
  _master/
    index.md                  # Hub landing page for /docs/ (optional)
  _overviews/                 # Tier 1 self-contained HTML overview pages
    architecture.html
    content-pipeline.html
    auth-deployment.html
  {project}/                  # Tier 2 markdown documentation
    _project.yaml             # Project metadata
    {subproject}/
      _subproject.yaml         # Subproject metadata + schema coverage
      index.md                 # Subproject landing page (optional)
      {page}.md                # Documentation pages

Overview Pages (`_overviews/`)

Files in content/_overviews/ are self-contained HTML documents with embedded CSS. They are served directly at /overview/{filename-without-extension} without any template wrapping. Each overview page must be registered in the overviewPages array in routes/overview.ts.

These pages use a visual style with flow diagrams, numbered steps, color-coded badges, and cards — designed as high-level summaries that link down to Tier 2 docs for detail.

Markdown Documentation

Naming Rules

Projects and subprojects are directory names — use lowercase with hyphens (e.g., ai-infrastructure)
Pages are .md filenames — the slug becomes the URL segment (e.g., overview.md -> /docs/dochub/api/overview)
Files and directories starting with _ or . are skipped by the nav tree builder and manifest generator
_master/index.md is special: it renders as the /docs/ landing page
index.md within a subproject renders as that subproject’s landing page

Metadata Files

`_project.yaml`

Required in each project directory. Read by ManifestService and MarkdownService for display names.

id: dochub
name: DocHub
description: Central documentation platform serving rendered HTML and JSON manifests

All fields are optional — if the file is missing, the directory name is used as both id and name.

`_subproject.yaml`

Required in each subproject directory. Contains the schema coverage declaration used by the manifest API and daily agent.

id: architecture
name: Architecture
description: Express app structure, services, middleware, and request flow
schema_coverage:
  purpose: true
  architecture: true
  variables: true
  api_endpoints: false
  handshakes: true
  data_model: false
  dependencies: true
  status: true

The schema_coverage map uses the 8 standard sections. Each is a boolean indicating whether the subproject’s documentation covers that topic. These values are manually declared — the system does not auto-detect coverage from content.

Page Frontmatter

Every .md file should have YAML frontmatter:

---
title: Page Title
summary: One-line description shown below breadcrumbs
order: 1
references:
  - target: dochub/api
    type: depends_on
  - target: dochub/deployment
    type: consumed_by
---

Field	Type	Default	Used By
`title`	string	filename slug	Nav sidebar, breadcrumbs, browser tab, manifests
`summary`	string	—	Below breadcrumbs on page, in manifests and search results
`order`	number	999	Sidebar sort order (lower = higher)
`references`	array	—	Manifests and daily agent cross-reference validation

Schema Sections

The 8 documentation schema sections that the daily agent evaluates:

Section	What It Covers
`purpose`	What the subproject does and why it exists
`architecture`	Components, structure, how things connect
`variables`	Environment variables, config files
`api_endpoints`	Routes, methods, request/response formats
`handshakes`	How it communicates with other subprojects
`data_model`	Database schemas, data structures, entities
`dependencies`	What it depends on, what depends on it
`status`	Current state, known issues, work in progress

There is no enforcement that content actually covers these sections — the _subproject.yaml declaration is a self-assessment that the daily agent reports on.

Environment Variables

Variable	Default	Effect on Content System
`CONTENT_DIR`	`./content`	Root directory for all documentation files. Passed to MarkdownService and ManifestService constructors
`SERVE_PREBUILT`	—	When set, serves pre-rendered manifests from `build/` instead of scanning the filesystem at request time

No other environment variables affect the content system directly. Database settings are irrelevant — all content is filesystem-based.

API Endpoints That Consume Content

The content system is read-only — it produces files that are consumed by API and docs routes:

Endpoint	What It Reads
`GET /api/manifest`	`_project.yaml` files, counts `.md` files per subproject
`GET /api/manifest/:project`	`_project.yaml`, `_subproject.yaml` files within a project
`GET /api/manifest/:project/:subproject`	`_subproject.yaml` (schema_coverage), all `.md` frontmatter
`GET /api/raw/:project/:subproject/:page`	Raw `.md` file content
`GET /api/search?q=term`	All `.md` files (recursive full-text search)
`GET /docs/*`	`.md` files rendered to HTML via MarkdownService
`GET /overview/:id`	`.html` files from `_overviews/` served directly

Service Interactions

Three services interact with the content directory:

Service	Reads	Produces	Called By
MarkdownService	`.md` files, `_project.yaml`, `_subproject.yaml`	Rendered HTML, nav tree, search results	`routes/docs.ts`, `routes/api.ts`
ManifestService	`_project.yaml`, `_subproject.yaml`, `.md` frontmatter	JSON manifest objects	`routes/api.ts`
TemplateService	`src/templates/styles.css`	Complete HTML pages wrapping rendered content	`routes/docs.ts`

The flow is: filesystem content -> MarkdownService/ManifestService (parse) -> TemplateService (wrap) -> HTML response.

The overview route bypasses all three services — it reads .html files from content/_overviews/ and serves them directly.

Dependencies

npm Packages Used by Content Processing

Package	Used In	Purpose
`markdown-it`	MarkdownService	Markdown to HTML rendering
`markdown-it-anchor`	MarkdownService	Heading anchor links and permalinks
`gray-matter`	MarkdownService	YAML frontmatter extraction from `.md` files
`highlight.js`	MarkdownService	Syntax highlighting in fenced code blocks
`js-yaml`	ManifestService	Parsing `_project.yaml` and `_subproject.yaml`
`glob`	ManifestService, MarkdownService	File pattern matching for content discovery

Internal Dependencies

The content system depends on the filesystem layout conventions documented above. It has no database dependencies — all data comes from files. The service layer depends on content following the naming rules and having valid YAML frontmatter/metadata.