BBSEngine Documentation

Welcome to the BBSEngine documentation handbook. This is the central
repository for all technical documentation, specifications, and
guides related to the BBSEngine project.

Quick Navigation

Getting Started

• README — project overview, install, repo tree, quick start
• Quick Start — five-minute first-run
• Security — security overview and links to the Phase 0-5
  hardening audit
• Router — /engine/router.php operation and post-mortems

Specifications

The canonical design specs live in specs/. Each
subsystem has one document; ADRs and end-to-end flows have their
own:

• Architecture
• Decisions (ADRs)
• Dependencies
• Flows — end-to-end message / request flows
• Database — pool, DSN, contextvars, SECURITY DEFINER
• Util — display, dates, logging, input, ranges, passwords
• Member — member subsystem + WebSocket handler
• Auth → Bank — WS login + bank authorization flow
• PG ident auth — per-member l_<loginid> / m_<moniker> roles
• Best practices — io.echo f-string rule, JSONB
  boundary
• Messaging — bbsengine6.message (Phase 11 layered package)
• Net layer — bbsengine6.net (transport, packets, registry)
• Console — admin CLI
• Module — bbsengine6.module registry / plugin loader
• Listbox — TUI listbox widget contract
• Blurb — content entity
• Folder — ltree-backed folder hierarchy
• Bottombar — fragment registry
• md2tpl — markdown → Smarty .tmpl converter

Security

• Phase 0-5 audit — every finding, every fix,
  every regression test

Documentation Structure

handbook/
├── index.md                 # this file
├── QUICKSTART.md            # five-minute first-run
├── SECURITY.md              # security overview + audit links
├── ROUTER.md                # /engine/router.php operation
├── specs/                   # per-subsystem design specs
│   ├── index.md             # spec directory TOC
│   ├── architecture.md
│   ├── decisions.md
│   ├── dependencies.md
│   ├── flows.md
│   ├── database.md
│   ├── util.md
│   ├── member.md
│   ├── auth-bank.md
│   ├── pg-ident-auth.md
│   ├── bestpractices.md
│   ├── messaging.md
│   ├── net-layer.md
│   ├── console.md
│   ├── module.md
│   ├── listbox.md
│   ├── blurb.md
│   ├── folder.md
│   ├── bottombar.md
│   └── md2tpl.md
└── modules.md               # placeholder; content forthcoming

Development

The handbook is written in plain Markdown. Chapters are rendered
at request time by engine/router.php via the shared
\bbsengine6\markdown\parseDocument primitive (matching teos's
teospath path). The handbook Makefile stage target rsyncs
the .md tree to WWWSTAGE/handbook/<v>/, where Apache +
mod_php + the rewrite in www/org/htaccess-prod route every
/handbook/<v>/... request to /engine/router.php for read-time
rendering (raw .md URLs go through /engine/router.php's
rawmarkdown handler, which streams the file as text/plain via
\bbsengine6\markdown\serveRawMarkdown() against TEOSDIR). The router detects the
/handbook/<v>/ URI prefix (canonicalized from $_SERVER['REQUEST_URI'],
unconditional since 2026-10-02 — see ROUTER.md),
sets TEOSDIR to the matching version tree, and dispatches
handleMarkdown for chapters, handleFolder for directories, and
handleIndex for the bare version URL. The bare version URL
(/handbook/<v>/) is matched by an explicit htaccess rule that forwards
it to the router with empty ?uri= so handleIndex probes the
index.md chapter. The make convert-tmpl developer helper converts
chapters into Smarty .tmpl snippets for embedding inside
other templates (e.g. chapter summaries on the org-site
front page).

Contributing

When adding new documentation:

1. Create Markdown files in the appropriate subdirectory.
2. Use clear, descriptive headings.
3. Include code examples where relevant.
4. Update the spec TOC in specs/index.md and the
   links in this file when adding a new doc.

Viewing Documentation

Documentation is best viewed through the web interface at:

• https://bbsengine.org/handbook/

Or read the Markdown files directly on GitHub.

Contact & Support

For questions about documentation or to suggest improvements:

• Check existing documentation and specs first
• Review the architecture guides
• Consult the module documentation
• Open an issue on the project tracker