Architecture

High-level overview of how ciderpress is structured, its design philosophy, and how data flows through the system.

Overview

ciderpress is a documentation framework for monorepos. It takes a single config file, syncs markdown content into a structured output directory, and builds a static site via Rspress. The information architecture -- sections, navigation, sidebar, landing pages -- is derived entirely from the config.

The codebase follows a functional, immutable, composition-first design. There are no classes, no let, no throw statements, and no loops. Errors are returned as Result tuples. Side effects (process exit, terminal output) are pushed to the outermost edges.

Package Ecosystem

packages

cli# CLI commands + sync engine (dev, build, serve, check, diff, draft, clean, setup, dump, sync)

ui# Rspress plugin, theme components, styles

config# @ciderpress/config — c12-based config loading, Zod validation

templates# @ciderpress/templates — Liquid template registry for draft command

theme# @ciderpress/theme — theme definitions and schema

ciderpress# ciderpress — public wrapper (re-exports config + ui + cli bin)

Package	Purpose
`@ciderpress/cli`	CLI commands + sync engine: dev, build, serve, check, diff, draft, clean, setup, dump, sync
`@ciderpress/ui`	Rspress plugin, React theme components, CSS overrides
`@ciderpress/config`	Config schema (Zod), type definitions, c12-based loading
`@ciderpress/templates`	Liquid template registry for the `draft` command
`@ciderpress/theme`	Theme definitions and schema
`ciderpress`	Public package: `.` and `./config` entry points + `ciderpress` CLI bin

`ciderpress` (wrapper)

The public-facing package. Two entry points and a CLI bin:

Entry	Purpose
`.`	Public API: `defineConfig`, `defineTheme`, `hasGlobChars`, `CiderpressLogo`
`./config`	Lightweight: just `defineConfig` + types

The ciderpress CLI bin is provided by this package and delegates to @ciderpress/cli. Users import defineConfig from ciderpress (or ciderpress/config) in their config file.

Layers

CLI Layer

Package: @ciderpress/cli

The command-line interface. Uses @kidd-cli/core for command routing. Styled terminal output goes through @clack/prompts (see packages/cli/src/lib/sync/index.ts:7). Commands orchestrate the core sync engine and Rspress build APIs. See CLI Reference for command details.

Core Layer

Package: @ciderpress/cli (sync engine lives at packages/cli/src/lib/sync/)

The sync engine. Config loading lives separately in @ciderpress/config. See Engine for pipeline details.

Module	Purpose
`lib/paths.ts`	Path constants for `.ciderpress/` output structure
`lib/sync/index.ts`	Main sync pipeline orchestrator
`lib/sync/errors.ts`	SyncError and ConfigError definitions
`lib/sync/types.ts`	Sync-specific type definitions
`lib/sync/copy.ts`	Page writing with frontmatter injection and hash tracking
`lib/sync/home.ts`	Default home page generation
`lib/sync/manifest.ts`	Incremental sync tracking via content hashes
`lib/sync/openapi.ts`	OpenAPI spec sync (dereference, MDX generation)
`lib/sync/openapi-spec.ts`	OpenAPI spec loading and dereferencing
`lib/sync/openapi-markdown.ts`	OpenAPI operation MDX generation
`lib/sync/images.ts`	Image discovery, copy, and path rewriting
`lib/sync/planning.ts`	Planning page discovery from `.planning/` directory
`lib/sync/rewrite-links.ts`	Relative link rewriting during copy
`lib/sync/strip-xml.ts`	XML tag stripping for planning documents
`lib/sync/workspace.ts`	Workspace item synthesis and card enrichment
`lib/sync/frontmatter.ts`	Frontmatter `parse(raw)` and `stringify(content, data)` (merge + hash live in `copy.ts`)
`lib/sync/resolve/index.ts`	Entry tree resolution (globs, text derivation, sorting)
`lib/sync/resolve/path.ts`	Path resolution utilities
`lib/sync/resolve/recursive.ts`	Recursive directory resolution
`lib/sync/resolve/sort.ts`	Entry sorting strategies
`lib/sync/resolve/text.ts`	Text derivation from filename/heading/frontmatter
`lib/sync/sidebar/index.ts`	Sidebar and nav JSON generation
`lib/sync/sidebar/inject.ts`	Virtual landing page generation (MDX)
`lib/sync/sidebar/landing.ts`	Landing page MDX generation
`lib/sync/sidebar/meta.ts`	Sidebar meta resolution
`lib/sync/sidebar/write-meta.ts`	Sidebar meta serialization
`lib/banner/index.ts`	SVG asset generation (banner, logo, icon)

UI Layer

Package: @ciderpress/ui

The Rspress theme and plugin:

Module	Purpose
`plugin.ts`	Rspress plugin: registers global UI components
`config.ts`	Rspress config factory: loads generated JSON, themes
`theme/index.tsx`	Theme entry: re-exports Rspress base + custom styles
`theme/components`	React components: sidebar, home, workspace cards
`theme/icons`	Iconify icon mappings for tech tags
`theme/styles`	CSS overrides for Rspress default theme

Data Flow

Error Handling

ciderpress uses the Result<T, E> tuple pattern for expected failures:

Layer	Strategy	Type
Core/sync	`Result<T, E>` tuples	`[error, null]` or `[null, value]`
Config	Returns `Result<T, ConfigError>` at boundary; CLI consumes and exits	`[ConfigError, null]` or `[null, CiderpressConfig]`
CLI	Consumes Result tuples, reports via `@clack/prompts`, calls `process.exit(1)`	`process.exit(1)` after logging (e.g. `dev-headless.ts:43-46`)

Design Decisions

Config is the information architecture -- A single file defines content structure, routing, navigation, and metadata. No separate sidebar/nav config files.
Factories over classes -- All components are factory functions returning plain objects.
Result tuples over throw -- Expected failures use Result<T, E>. No exceptions.
Incremental sync -- Mtime checks, content hashes, and config hashes skip unchanged work. Manifest comparison removes stale files.
Virtual pages via MDX -- Landing pages are generated at sync time as MDX with React components.
Multi-sidebar from config -- Isolated sections get independent sidebar namespaces automatically.
Glob-driven content discovery -- Patterns auto-discover files without manual entry per page.
Frontmatter inheritance -- Entries inherit frontmatter from ancestors in the config tree.

#Architecture

#Overview

#Package Ecosystem

#ciderpress (wrapper)

#Layers

#CLI Layer

#Core Layer

#UI Layer

#Data Flow

#Error Handling

#Design Decisions

#References