> Draft ? This document was generated by AI and may not have been reviewed for accuracy. It represents a proposed analysis only and should not be treated as authoritative without human review.

BinktermPHP Documentation & Positioning Review

Executive Summary

The documentation lags significantly behind the project's actual capabilities. The docs/DEVELOPER_GUIDE.md architecture section describes five components; the actual running system has at least a dozen daemons, three transport layers, a multi-modal door subsystem, an AI pipeline, and a mesh radio gateway. The gap between what the project is and what it says it is is wide enough to discourage serious contributors and confuse integrators.

The core problem is structural: the docs were written for a BBS, then features were added. The narrative never caught up. The platform identity problem flows from this ? the project reads like nostalgia software that got AI bolted on, when it's actually a well-engineered multi-protocol community platform that uses FTN as its networking backbone.

1. Architectural Clarity

What's Missing

The daemon constellation is undocumented as a system. docs/DEVELOPER_GUIDE.md lists five components, but a production install can run twelve or more processes:

binkp_server          binkp_poll/scheduler
admin_daemon          realtime_server (BinkStream)
mcp-server            mrc_daemon
telnet_daemon         ssh_daemon
gemini_daemon         multiplexing-server (Node.js)
echomail_robots       binkp_poll (triggered)

Nothing shows how these communicate. A new contributor has no map. The AdminDaemon's role as a coordination hub (logging relay, config writes, task triggers) is described in one paragraph in CLAUDE.md but nowhere in the user-facing docs.

The FTN packet lifecycle is never diagrammed. This is the core architectural concept. What happens from "binkp connection accepted" to "message visible in the web UI"? Inversely, what happens from "user clicks Post" to "packet leaves the system"? The packet processing path touches scripts/binkp_server.php ? data/inbound/ ? src/MessageHandler.php ? database ? sse_events ? browser ? none of this is shown anywhere.

The realtime architecture exists in one place only. docs/BinkStreamChannel.md is genuinely excellent documentation ? the ASCII diagram, the transport-fallback logic, the cursor design rationale ? but it is siloed. The overall developer guide does not reference it as an architectural landmark, so it reads like a subsystem doc rather than a core design document.

The template layering system is described but not diagrammed. Custom > Shell > Default is a three-layer override system. New contributors trip on this because there is no visual showing what resolves where and why both templates/base.twig and templates/shells/web/base.twig must be updated.

The shared web/terminal session architecture is never explained. The developer guide says Telnet and SSH "use the REST APIs" and share BbsSession. That is the entire explanation. How does a terminal session drive the PHP API? What is the authentication model for a PTY session? What can the terminal do that the web cannot (and vice versa)?

Diagrams That Should Exist

1. System Architecture (the most urgent missing item)

???????????????????????????????????????????????????????
?                   CLIENT LAYER                       ?
?  Browser ????? WebSocket/SSE ??????????????????????? ?
?  Telnet/SSH ?????????????????????????????????????  ? ?
?  PacketBBS / Mesh Radio ??????????????????????  ?  ? ?
?  AI Client (MCP) ?????????????????????????   ?  ?  ? ?
?  QWK Offline Reader ??????????????????   ?   ?  ?  ? ?
?????????????????????????????????????????????????????? ?
                                       ?   ?   ?  ?     ?
??????????????????????????????????????????????????????? ?
?                  ACCESS LAYER        ?   ?   ?  ?   ? ?
?  PHP Web + Routes ????????????????????   ?   ?  ?   ? ?
?  realtime_server (BinkStream WS) ?????????   ?  ?   ? ?
?  telnet/ssh_daemon ???????????????????????????  ?   ? ?
?  mcp-server (Node.js) ???????????????????????????   ? ?
??????????????????????????????????????????????????????? ?
                        ?
???????????????????????????????????????????????????????
?                  SERVICE LAYER                       ?
?  admin_daemon  ???? logging, config writes, tasks    ?
?  mrc_daemon    ???? MRC chat relay                   ?
?  gemini_daemon ???? Gemini protocol capsule          ?
?  multiplexing-server ?? DOS/Native door PTY bridge   ?
???????????????????????????????????????????????????????
                        ?
???????????????????????????????????????????????????????
?               FTN NETWORKING LAYER                   ?
?  binkp_server    ???? incoming binkp connections     ?
?  binkp_poll      ???? outbound polling               ?
?  binkp_scheduler ???? polling schedule management    ?
???????????????????????????????????????????????????????
                        ?
???????????????????????????????????????????????????????
?                   DATA LAYER                         ?
?  PostgreSQL ???? all persistent data                 ?
?  data/inbound/  ?? received FTN packets              ?
?  data/outbound/ ?? queued FTN packets                ?
?  data/logs/     ?? structured log files              ?
???????????????????????????????????????????????????????

2. FTN Packet Lifecycle ? inbound and outbound separately

3. Door game subsystem ? browser ? WebSocket ? multiplexing-server ? PTY/DOSBox-X ? ANSI back

4. AI pipeline ? user prompt ? src/AI/MessageAiAssistant.php ? MCP tools ? echomail tables ? model ? response

5. BinkStream transport decision tree ? already exists in docs/BinkStreamChannel.md, should be linked prominently from docs/DEVELOPER_GUIDE.md

Hidden Strengths Being Undersold

• BinkStream transport abstraction ? a single `window.BinkStream` API that transparently switches between WebSocket and SSE, with SharedWorker fan-out across tabs and cursor-based reconnect continuity. This is production-quality frontend architecture that should be highlighted as a design achievement.
• WebDoor SDK ? the `webdoor.json` manifest pattern and shared SDK create a first-class extension point for browser games with automatic credit integration.
• Multi-network FTN support ? simultaneous connections to multiple independent FTN networks is non-trivial and is not mentioned prominently anywhere.
• MCP server with per-user bearer keys and BBS access-control enforcement ? a genuinely novel integration pattern for this domain.
• PacketBBS bridge adapter architecture ? the `bridge_node_id` vs `node_id` session separation shows real systems thinking and is more architecturally interesting than the documentation conveys.

2. Documentation Structure

Proposed Restructured docs/index.md

The current structure organizes by feature area, which serves sysops but fails developers and evaluators. The implied reading order is "setup ? features" with no concept of architecture or onboarding path.

Proposed:

## Platform Overview
- Architecture Overview       (docs/ARCHITECTURE.md ? new)
- Daemon Reference            (docs/DAEMONS.md ? new)
- Data Model                  (docs/DATA_MODEL.md ? new)

## Getting Started
- Installation
- Configuration Reference
- Quick Start: Your First FTN Connection

## Access Methods
- Web Interface
- Terminal Server (Telnet)
- SSH Server
- PacketBBS / Mesh Radio Gateway
- Gemini Capsule
- QWK Offline Reader

## FTN Networking
[unchanged]

## Real-Time & AI
- BinkStream Back-Channel      (PROMOTED from Developer Reference)
- AI Assistant
- AI Bots
- AI Providers and Usage
- MCP Server
- MCP Client Help

## Doors & Games
[unchanged]

## Communication & Chat
[unchanged]

## Content & Media
[renamed from "Content & Display"]

## Economy & Engagement
[unchanged]

## Automation
[unchanged]

## Deployment & Infrastructure
[unchanged]

## Developer Reference
- Developer Guide
- API Reference
- BinkStream Back-Channel
- Admin Terminal
- Contributing             (CONTRIBUTING.md ? already exists in project root; link from here)

## Upgrading
[unchanged]

New Documents That Should Exist

docs/ARCHITECTURE.md ? the highest-priority missing document. Full daemon map, component diagram, data flow diagrams for inbound FTN packet and outbound message post, IPC model between daemons.

docs/DAEMONS.md ? all processes, their purposes, required vs optional status, start/stop commands for both dev and production, PID files, log files.

docs/DATA_MODEL.md ? key tables and their conceptual relationships. Not a schema dump ? a mental model for developers. Key tables: echomail, netmail, users, echoareas, sse_events, user_transactions, chat_messages.

CONTRIBUTING.md (already exists in the project root) ? verify it covers git workflow, PR targets (claudesbbs), i18n checklist, and pre-commit checks. Ensure it is linked from docs/index.md and docs/DEVELOPER_GUIDE.md.

Developer Guide Problems

The "Project Architecture" section in docs/DEVELOPER_GUIDE.md is approximately 500 words describing five components. The project has 80+ source files in src/, ten or more daemons, and multiple language runtimes (PHP and Node.js). The section needs to be at minimum triple its current length and include at least one diagram.

The "Key Features" list at the bottom of docs/DEVELOPER_GUIDE.md reads like marketing copy. It lists features but explains no architecture. What would help is a "Design Decisions" section explaining why things are the way they are: why a SharedWorker instead of per-tab SSE? Why PostgreSQL triggers for sse_events instead of pushing from the application layer? Why a separate AdminDaemon for config writes?

Missing Workflow Examples

• "Add a new API endpoint end-to-end" ? routes ? handler ? i18n keys ? `docs/API.md` update ? test
• "Add a new BinkStream event type" ? partially covered in `docs/BinkStreamChannel.md`, but should be linked from the developer guide with a one-paragraph orientation
• "Write a WebDoor from scratch" ? tutorial, not just reference
• "Write a new echomail robot" ? `docs/Robots.md` describes configuration but not authoring

3. Platform Identity

The Core Problem

The README opens with:

> BinktermPHP is a modern web-based BBS that combines classic FTN packet processing...

"Modern web-based BBS" positions the project against other BBS software (Mystic, Synchronet, WWIV). That is the wrong comparison class. The project's actual peers are closer to Discourse or Mattermost with FTN networking and retro aesthetics.

The second problem is the origin story:

> binkterm-php was largely written by Anthropic's Claude with prompting by awehttam. It was meant to be a fun little exercise...

At version 1.9.6 with a YouTube feature, production deployments, and an active community, leading with "fun little exercise" is a credibility problem. It reads as a preemptive apology for code quality. The origin story is genuinely interesting ? but "Claude wrote most of this" is a differentiator in 2026, not a disclaimer.

Positioning Options

Option A (broadest) ? preferred: > BinktermPHP is a multi-protocol community platform built on FTN networking. It delivers a full BBS experience through web, telnet, SSH, mesh radio, and AI interfaces ? all sharing the same message database and real-time event system.

Option B (developer-targeted): > A PHP/PostgreSQL platform for running FTN-connected communities. Native binkp mailer, real-time WebSocket/SSE messaging, AI-integrated message reader, WebDoor game SDK, and mesh radio gateway ? accessible from browser, terminal, or AI assistant.

Option C (operator-targeted): > Run a modern FidoNet-connected BBS. Browser UI, ANSI terminal, SSH, or mesh radio ? the same messages everywhere. Drop in door games, connect to multiple FTN networks, let users chat with an AI assistant about the echomail they're reading.

The point is: none of these say "classic" or lead with nostalgia. They state capability.

Terminology to Standardize

| Current (inconsistent) | Recommended | |---|---| | "echo areas" / "echomail areas" / "echoareas" | echo areas ? two words, lowercase | | "FidoNet" / "Fidonet" / "FTN" | FTN for the protocol family; FidoNet for the specific Zone 1 network | | "door games" / "Doors" / "door software" | doors (lowercase) for the category; DOS Doors, Native Doors, WebDoors, JS-DOS Doors as named types | | "WebDoors" / "Web Doors" / "web-based doors" | WebDoors ? one word, title case; it is a branded subsystem | | "PacketBBS" / "PacketBBS Gateway" | PacketBBS Gateway for the feature; PacketBBS as the short name | | "Credits" / "credit system" / "credits economy" | Credits (title case) when referring to the feature; lowercase when generic | | "MCP server" / "MCP Server" | MCP Server ? named component |

4. Developer Experience

API Issues

No concept of core vs extended API. The API reference has 47 message endpoints, 33 user endpoints, 23 binkp endpoints. A new integrator has no sense of where to start. The docs/API.md reference needs a "Getting Started" section at the top identifying the minimum endpoints needed for common tasks.

Authentication flow is underdocumented. The docs/API.md header says to log in via POST /api/auth/login to receive a session cookie. It does not show what a successful response looks like, what the CSRF token situation is, or how to structure subsequent requests. A complete auth example (request + response) should be the first concrete content in the API reference.

No error response example. The API uses structured errors with error_code and error fields ? this is a good design ? but there is no example of what a real error response looks like in the docs/API.md introduction.

API versioning is absent. All endpoints are under /api/ with no version segment. This should at least be acknowledged as a conscious decision in the developer guide so contributors do not add versioning inconsistently.

No external event subscription mechanism. External systems can integrate by polling the API, but there is no push mechanism exposed externally. The BinkStream SSE endpoint requires session auth. This is a gap for automation integrations.

Organically Grown vs Intentionally Designed

Organically grown (needs documentation explaining the design):

• Template resolution order (`templates/custom/` ? `templates/shells/<shell>/` ? `templates/`) ? clearly evolved rather than was designed; the rationale for the three-layer system is nowhere explained
• The AdminDaemon's accumulated responsibilities ? it started as a logger and grew to include config write coordination and task triggers without a unifying design document
• PHP migration vs SQL migration distinction ? the "why would I choose PHP?" decision point needs a clearer answer than the current one-line note in `docs/DEVELOPER_GUIDE.md`

Intentionally designed (should be called out as such):

• BinkStream transport abstraction (WS/SSE/SharedWorker) ? clearly designed, excellently documented in `docs/BinkStreamChannel.md`
• WebDoor SDK with `webdoor.json` manifests ? a deliberate extension architecture
• Credits system security model (server-side transactions only, never exposed to client) ? clearly designed and documented; a good example for other security decisions
• FTN multi-network support ? deliberate, but undersold

5. Public Presentation

README Structural Issues

The feature list in README.md has no hierarchy ? "Credits economy" appears next to "Nodelist browser" with equal visual weight. Some features are architecturally foundational; others are useful extras. The presentation does not distinguish between them.

Proposed README structure:

# BinktermPHP

BinktermPHP is a multi-protocol community platform built on FTN networking. It delivers a full BBS experience through web, telnet, SSH, mesh radio, and AI interfaces ? all sharing the same message database and real-time event system.

## What Makes It Different
- Built-in binkp mailer (not a web frontend for another BBS)
- Multi-protocol: web, terminal, SSH, mesh radio ? same data everywhere
- AI-native: MCP Server, in-reader AI assistant, configurable AI bots
- WebDoors: drop-in HTML5 games with automatic credit integration
- Real-time: BinkStream WebSocket/SSE with SharedWorker fan-out across tabs

## Platform Access Methods
[visual table]

## Core Features
[architectural features, 2-3 bullets each]

## Optional Components
[clearly labeled as optional]

## Installation
[...]

The Origin Story

Remove it. The current text reads as a preemptive apology for code quality. At v1.9.6 with production deployments and a YouTube feature, the software speaks for itself.

What to Remove or Simplify

• "...and more" at the end of the README feature list ? list the features or do not; "and more" signals abandoned effort
• HTML <table> for screenshots ? breaks plaintext rendering; standard Markdown image syntax works
• Duplicate content between CLAUDE.md and docs/DEVELOPER_GUIDE.md ? `CLAUDE.md` contains better architecture documentation than the developer guide; reconcile rather than maintain two sources

Prioritized Recommendations

Immediate (high leverage, low effort)

1. Rewrite the README opening paragraph. One better positioning sentence changes how every evaluator frames the project.
2. Add a daemon reference table to docs/DEVELOPER_GUIDE.md. A single table: daemon name, purpose, required/optional, log file, PID file, start command. High value for contributors.
3. Add the system architecture ASCII diagram (or a version of it) to the architecture section of `docs/DEVELOPER_GUIDE.md`. An imperfect diagram beats no diagram.
4. Link docs/BinkStreamChannel.md from the architecture section of `docs/DEVELOPER_GUIDE.md` with a sentence explaining its significance.
5. Add an auth quickstart to docs/API.md ? one complete request/response pair showing login ? cookie ? authenticated request, at the top of the file before the endpoint listing.

Medium Term

6. Create docs/ARCHITECTURE.md ? the core missing document. System diagram, daemon map, data flow for inbound FTN packet and outbound message, IPC model between daemons.
7. Expand the Developer Guide architecture section from ~500 words to ~2000 with diagrams and the FTN packet lifecycle.
8. Standardize terminology across all docs according to the table in Section 3.
9. Add an "Authentication" section to docs/API.md with a real request/response example before the endpoint listing.

Longer Term

10. Link CONTRIBUTING.md (project root) from `docs/index.md` and `docs/DEVELOPER_GUIDE.md` ? it already exists but is not surfaced in the developer documentation.
11. Create docs/DATA_MODEL.md ? key tables and their conceptual relationships as a mental model for developers.
12. Add a WebDoor tutorial ? "write a WebDoor in 30 minutes" end-to-end walkthrough.
13. Restructure docs/index.md to lead with Architecture and promote the AI/realtime section out of last place.

Summary

The project's documentation describes a BBS. The project is a multi-protocol communications platform. Closing that gap is the most impactful documentation work available. The architecture, the AI integration, the multi-modal access story, and the realtime infrastructure are all genuinely impressive ? none of them are communicated well to someone arriving at the project for the first time.