Where this is going

Sextile began as one program that was two things at once: a Viewdata application server, and the Stardot service running on it. This document records the architecture it is moving towards, and why. architecture.md describes what exists today.

Four layers

   phpBB                          the system of record: posts, users,
     |                            permissions, attachments
     |  forum-native services
     v
   Stardot Content Provider API   a phpBB extension exposing forum concepts
     |                            over HTTP/JSON, for any front end
     |  HTTP/JSON, localhost
     v
   stardot-viewdata               a Sextile application: the Stardot
     |                            information architecture in Viewdata
     |  Sextile application interfaces
     v
   Sextile                        the framework: connections, sessions,
     |                            routing, protocol, frames
     |  Viewdata over TCP
     v
   Viewdata clients               a stateless display terminal

Why the boundaries fall there

The lifecycle argument in its framework form is in Why Sextile; this is the same fact read as a strategy for integrating with phpBB.

The lifecycle mismatch is the decisive argument. phpBB is built around a short-lived request: bootstrap, authenticate, query, render, end. A Viewdata service is the opposite shape — a connection opens, and the session lasts until the caller rings off, holding the current page, the navigation history, entered input and eventually authentication. A Viewdata terminal is a dumb display holding nothing but the frame on screen, so the server holds all of it, and the TCP connection is the session’s container.

Making phpBB own that lifetime would mean writing a long-running PHP daemon that happens to bootstrap phpBB — which is Sextile rewritten in PHP, and the wrong consequence of accepting closer integration. Splitting it the other way turns the mismatch into an advantage: phpBB provides resources; Sextile provides conversations with those resources. Each call into phpBB stays an ordinary phpBB request, answered and forgotten, while Sextile keeps a caller connected for three hours with no phpBB request open between calls.

Content adaptation and presentation adaptation are different jobs. The extension converts phpBB internals into clean forum-domain resources. stardot-viewdata converts forum-domain resources into a Viewdata application. Keeping those in separate components is what makes each replaceable.

Two invariants

These are the falsifiable form of the design. If either fails, a boundary has moved and should be moved back.

1. It must be possible to write another consumer of the Stardot Content Provider API that knows nothing about Viewdata. So no page numbers, frame sizes, control codes, 40-column wrapping or keypad conventions may appear in that API. If they do, the boundary has drifted into PHP.

2. It must be possible to write another Sextile application that knows nothing about phpBB or Stardot. So no bbcode_uid, ACL tables, database schema or forum vocabulary may appear in the framework. If they do, the boundary has drifted into Python.

The second invariant is checkable today: the calendar keeps checking it in-tree, and the weather service does so from its own repository.

Phases

1. Framework extraction — separate Sextile from stardot-viewdata, leaving the application working exactly as it does now, against the SQLite archive and the Atom ingest. Nothing here depends on anyone else. This is the phase in progress.

2. A phpBB to develop against — stand up a local vanilla phpBB, which is what Stardot is said to be, so the extension can be built and tested without touching the live board.

3. The Stardot Content Provider API — the phpBB extension itself: a composer.json, services registered in phpBB’s DI container, a controller and routes, and later event listeners for changes. Small, in the end: a few thin adapter classes. The interesting work is deciding which phpBB abstraction to retrieve posts through, and how much interpretation belongs on the PHP side.

4. stardot-viewdata onto the API — replace the Atom source and the SQLite archive with the content provider. The page numbering and the rendering should not need to change, which is the point of doing phase 1 first.

Two questions are deliberately left until they are reached: who owns the mapping between Viewdata page numbers and phpBB topic ids, and what becomes of the local archive once the board can be asked directly.

Names

Sextile — the Viewdata application-server framework. stardot-viewdata — the Sextile application implementing the Stardot service. Stardot Content Provider API — the phpBB extension exposing the source material. Named for its responsibility rather than its current consumer, because a Viewdata service is only the first front end it could serve.

The reasoning is recorded at length in the repository, at docs/discussions/ChatGPT-phpBB-extension-integration.md, with a sketch of the same picture beside it.