Float.BBS Viewer Architecture Decision

ctx:: 2025-10-26 @ 03:30 PM - [project::float-bbs-viewer]

Context

Building local markdown file viewer for float-hub/float.dispatch with BBS aesthetic. Point at filesystem directory, render markdown, resolve wikilinks, navigate the zine.

Decision: Website First, TUI Later

Website (Phase 1 - NOW)

• Web-based markdown viewer
• File-based routing
• Wikilink resolution + navigation
• BBS brutalist aesthetic
• Local dev server (not production deploy)

TUI (Phase 2 - LATER)

• Rust + ratatui implementation
• Pure terminal aesthetic (ultimate sysop vibe)
• TUI foundations already documented (see: 2025-10-17-rust-tui-architecture-guide.md)
• Longer timeline, separate project

Recommended Stack (Website)

Astro + Solid.js

Why Astro

• Markdown-native (perfect for content-focused viewer)
• File-based routing built-in (src/pages/[...slug].astro)
• Fast, minimal JS (shacks not cathedrals)
• Static generation OR dev server mode
• Can point at external directory via content collections

Why Solid.js (vs React)

• Lightweight, reactive
• Fits brutalist aesthetic (minimal overhead)
• Fine-grained reactivity (good for file watching)
• Can reuse existing Shadcn patterns if needed

Alternative Stack

Next.js App Router - If Astro feels wrong during spike

• Familiar file-based routing
• React ecosystem (existing v0 project patterns)
• Dynamic routes: app/[...path]/page.tsx

Core Features

Must Have (v1)

1. Multi-directory reading - Point at:
   • ~/float-hub/float.dispatch (zine/imprints)
   • ~/float-hub (root - includes inbox, operations)
   • ~/.evans-notes/daily (daily notes, bones, tldr, sprint files)
2. Markdown rendering - Frontmatter aware
3. Wikilink resolution - [[filename]] → navigate to file (across all directories)
4. File-based routing - /path/to/file renders that markdown
5. BBS aesthetic - Brutalist design, ASCII art preserved

Nice to Have (v2)

1. Search - Filter by frontmatter (type:, context:, status:)
2. Backlinks - “What links here?” graph
3. Daily notes - Detect YYYY-MM-DD pattern
4. file_id.diz.md - Special BBS info block rendering
5. Live reload - Watch filesystem for changes

Skip (YAGNI)

• Authentication (local only)
• Database (filesystem IS the database)
• Write operations (read-only viewer)
• Complex build (dev server sufficient)

Wikilink Resolution Strategy

Patterns to Support

[[filename]]                 → Search across all configured directories
[[path/to/file]]            → Relative path resolution
[[YYYY-MM-DD]]              → Daily notes in ~/.evans-notes/daily/
[[2025-W##-rangle-vibe]]    → Weekly retrospectives in float.dispatch

Multi-Directory Strategy

Configured Roots:

• ~/float-hub/float.dispatch - Imprints, zine content
• ~/float-hub - Inbox, operations, project root
• ~/.evans-notes/daily - Daily notes ecosystem

Unified Navigation:

• All markdown files indexed at startup
• Wikilink resolution searches across all roots
• File-based routing preserves directory structure
• Example: /evans-notes/daily/2025-10-26 → ~/.evans-notes/daily/2025-10-26.md

Resolution Algorithm

1. Check same directory
2. Check parent directory (breadcrumb up)
3. Search across all configured roots (float-hub + evans-notes)
4. Fall back to search results page (list all matches)

Implementation

• Pre-scan: Build unified wikilink → filepath map from all roots
• Fast lookup: O(1) resolution for most links
• Watch mode: Watch all configured directories, rebuild map on changes
• Index structure: Store full paths but display relative to root for UX

BBS Aesthetic Integration

Visual Design

• Brutalist palette: Use v0-brutalist-palette-scaffold colors
• Monospace fonts: For file_id.diz.md blocks
• ASCII art: Preserve box-drawing characters (═══)
• Terminal-inspired: Console cowboy vibes

Navigation as BBS Metaphor

/                         → BBS main menu (unified index)
/float-dispatch/imprints  → Publishing house (themed collections)
/rangle-weekly            → Work journal area
/ritual-forest            → Consciousness tech library
/sysops-daydream          → TUI experiments + float.bbs concepts
/evans-notes/daily        → Daily notes archive
/evans-notes/bones        → Knowledge wrap files
/float-hub/inbox          → Incoming deliveries

Multi-Root Navigation:

• Each root gets menu entry
• Unified search across all roots
• Cross-root wikilinks work seamlessly
• Each markdown file = BBS text file

Implementation Phases

Phase 0: Spike/Prototype (2-3 hours)

• Set up Astro project
• Configure multi-root reading (float-hub + evans-notes)
• Render single markdown file from each root
• Prove cross-root wikilink resolution works
• Test daily note navigation (YYYY-MM-DD)
• Decision point: Continue Astro OR pivot to Next.js

Phase 1: Core Viewer (1 day)

• Dynamic routing for all .md files
• Wikilink resolution + navigation
• Frontmatter display
• Basic brutalist styling
• file_id.diz.md special rendering

Phase 2: Navigation (1 day)

• Unified index page (all roots)
• Imprints index (float.dispatch/imprints)
• Daily notes archive (evans-notes/daily)
• Weekly retrospectives navigation
• Search by frontmatter (across all roots)

Phase 3: Polish (½ day)

• BBS aesthetic refinement
• ASCII art rendering perfected
• Live reload on file changes
• Keyboard shortcuts (j/k navigation?)

Phase 4: Package (optional)

• Tauri wrapper for standalone app
• OR: Keep as dev server (simpler)

TUI Roadmap (Future)

When to Build TUI

• After website version proves wikilink resolution works
• When craving pure terminal aesthetic
• As separate project: float-bbs-tui

TUI Features

• File navigation via keyboard
• Markdown rendering in terminal (challenge: complexity)
• Pure sysop aesthetic (no browser needed)
• Reference: 2025-10-17-rust-tui-architecture-guide.md (already documented)

Tech Stack

• Rust + ratatui
• markdown-rs for parsing
• Custom wikilink resolver
• Longer timeline (more complex than web)

Next Steps

1. Create repo: float-bbs-viewer (or float.bbs-local)
2. Spike Astro: Prove wikilink resolution + routing
3. Decision: Continue OR pivot to Next.js
4. Phase 1: Core viewer implementation
5. Integrate: Existing v0 brutalist design system

Configuration Example

Astro multi-root setup:

// astro.config.mjs
export default {
  content: {
    collections: {
      floatDispatch: {
        type: 'content',
        directory: '/Users/evan/float-hub/float.dispatch'
      },
      floatHub: {
        type: 'content',
        directory: '/Users/evan/float-hub'
      },
      evansNotes: {
        type: 'content',
        directory: '/Users/evan/.evans-notes/daily'
      }
    }
  }
}

Unified Index Strategy:

• Scan all collections at build/startup
• Build unified wikilink map (all roots indexed together)
• Route /[root]/[...path] to appropriate collection
• Cross-collection wikilinks resolve via unified map

Related Work

• Complements: float.dispatch zine infrastructure (just built)
• Uses: v0-brutalist-palette-scaffold design system
• Bridges: Desktop reading ↔ file-based authoring
• Enables: Local-first markdown vault exploration (float-hub + evans-notes unified)

Decision Date: 2025-10-26 Decided By: Exploratory conversation with kitty claude Status: Planning → Ready for spike Next Action: Create Astro spike project