▌ The Exchange

Building the Phosphor Parser — Week 1 Dev Log

July 30, 2026

The first phase of Phosphor implementation is underway. Here’s what’s happening and why it matters.

The Problem

Every BBS system has the same issue: configuration is either too rigid (hardcoded in the application) or too generic (a config file that can’t express behavior). You want to add a new menu item? Edit Java, recompile, restart. You want a custom login handler? Write a plugin, package it, deploy it. You want to send mail to new users automatically? More Java, more compilation, more restarts.

This kills experimentation. You can’t iterate on the BBS experience when every change requires a build cycle.

The Phosphor Approach

Phosphor is a domain-specific language designed for exactly this problem. Two layers:

Declarative — describe the BBS structure (menus, boards, channels, file areas, themes) in a readable syntax. The BBS syncs this to the database on file save. No restart.

bbs "The Exchange" {
    menu "Main" {
        'B' "Message Boards"  -> boards
        'C' "Live Chat"       -> chat
        'Q' "Logout"          -> disconnect
    }

    board "General" {
        description = "General discussion"
        federated = true
    }
}

Imperative — define behavior with event handlers. When a user logs in, when a post is created, when a chat message arrives — Phosphor handles it.

on login {
    if user.first_login {
        show "welcome.ans"
        mail from "SysOp" to user {
            subject = "Welcome to The Exchange!"
            body = "Welcome aboard, ${user.display_name}!"
        }
    }
}

What’s Being Built (Phase 1)

Phase 1 is the declarative layer — the foundation everything else builds on:

  1. Lexer/Tokenizer — breaks .phos source into tokens (keywords, identifiers, strings, operators)
  2. Parser — builds an AST from tokens for the declarative subset (bbs, group, menu, board, chat, file_area, theme)
  3. Declarative Processor — syncs the AST to the database (same pattern as the existing syncMenuItems code)
  4. Hot-Reload — watches .phos files for changes, re-parses, re-syncs, all without restart
  5. BBS Wiring — integrates the Phosphor runtime into the BBS startup

The key constraint: the jterm-phosphor module depends only on jterm (the terminal framework), not on jterm-bbs. This keeps the language reusable — Phosphor could power other BBS systems built on jterm.

The Test Strategy

Every component gets tests first (TDD). The lexer has tests for tokenizing every block type. The parser has tests for parsing every construct. The processor has tests for syncing to the database. And when Phase 7a comes around, the testing framework itself gets tested by — itself.

More importantly, all Phosphor tests run in mvn test alongside the existing Java tests. Same JUnit, same Surefire, same reports. No separate test runner. No separate CI step.

What’s Next

Phase 2 adds the imperative layer — the expression evaluator, event handlers, and the reactive binding system. That’s where Phosphor goes from “config file” to “programming language.” But first, Phase 1 needs to be solid. The parser needs to handle every declarative construct. The hot-reload needs to be reliable. The database sync needs to be idempotent.

One step at a time.