---
description: About BBS-MD and its design philosophy
---

# About BBS-MD

## What Is This?

BBS-MD is a terminal-based markdown vault reader that channels the aesthetic of 1990s bulletin board systems. It turns a folder of markdown files into a navigable, interlinked information system — like a personal wiki you browse over SSH.

## Design Philosophy

### Terminal-Native

BBS-MD is built for the terminal. No web browser, no Electron, no GUI toolkit. Just your terminal emulator, a monospace font, and 16 colors. It runs over SSH, in tmux, on a Raspberry Pi, on a VPS — anywhere you have a shell.

### Vault as Filesystem

Your content is just markdown files in a directory. No database, no proprietary format, no lock-in. Edit with vim, VS Code, or `echo >>`. BBS-MD watches for changes and refreshes live.

### Retro Aesthetic

The CGA 16-color palette isn't a limitation — it's a feature. Box-drawing characters for code blocks and tables. ANSI art on the landing page. Reverse-video status bar. Every design choice asks: *would a SysOp in 1994 approve?*

### Safe by Default

BBS-MD is designed to run as a login shell. That means:

- A panic must never leave the terminal broken
- A disconnect must never corrupt state
- The user must always be able to exit
- The app must always restore the terminal

These aren't nice-to-haves. When your app *is* the shell, safety is the foundation.

## Tech Stack

| Component      | Technology        |
|----------------|-------------------|
| Language       | Rust (Edition 2024) |
| TUI Framework  | ratatui 0.30       |
| Terminal       | crossterm           |
| Markdown       | pulldown-cmark (GFM) |
| Highlighting   | syntect             |
| ANSI Art       | ansi-to-tui         |
| File Watching  | notify 6.1          |
| Dir Traversal  | walkdir 2.5         |

## Architecture

```
bbs-md/
  src/
    main.rs        Entry point, terminal init, event loop
    app.rs         App state, navigation, key handling
    config.rs      TOML config loading (bbs.toml)
    vault.rs       Document loading, wiki-link resolution
    renderer.rs    Markdown-to-styled-lines pipeline
    highlighter.rs Syntax highlighting with CGA colors
    splash.rs      ANSI art splash screen loader
    signals.rs     Unix signal handlers (SIGHUP, SIGTERM)
    terminal.rs    Terminal init/restore, panic hook
  vault/
    index.md       Landing page (splash.txt prepended)
    splash.txt     ANSI art header (optional)
    *.md           Your content lives here
```

> BBS-MD is a single binary with no runtime dependencies. Compile it, drop it on a server, point it at a vault.

Back to [[index|home]] or read the [[Changelog]].