KB2MOB BBS
# Packet BBS — v0.1 Architecture & Design Specification
## 1. Project Philosophy
This project is a modern, lightweight BBS inspired by classic systems such as C-Net and Mystic, but designed specifically with packet radio as a future transport.
The BBS should:
* Be useful and enjoyable as a standalone local BBS. * Preserve the nostalgia and character of classic BBS systems. * Use modern, maintainable software internally. * Remain useful without an Internet connection. * Avoid unnecessary complexity. * Separate BBS functionality from communications transports. * Allow future packet-radio functionality to be added without rewriting the BBS core.
The initial version will have no radio or packet connectivity.
The first goal is a stable local BBS.
—
# 2. Initial Scope
Version 0.1 will provide a local-console BBS with:
* Users * Access levels * Message boards * Threaded messages * Per-user unread/read tracking * Private messaging * File areas * ANSI screens and colors * External screen/template files * Main menu and hierarchical submenus * User preferences * Logging * Configuration * SQLite database * Sysop functionality through the local interface
Future transports will be added later.
—
# 3. High-Level Architecture
The system will be modular.
```text
BBS CORE
|
+-------------------+-------------------+
| | |
v v v
Data Layer Services Layer UI Layer
| | |
SQLite Users/Messages/etc. ANSI Renderer
Screen Files
|
+----------------------------------------+
|
Local Interface
```
Future transports will connect to the same BBS services:
```text
BBS CORE
|
+-------------------+-------------------+
| | |
Local Telnet AX.25
|
Dire Wolf
```
The BBS core must not depend on any particular transport.
—
# 4. Database
SQLite will be used as the initial database.
The database will be relational, with separate tables for logically distinct entities.
Initial tables:
* `users` * `boards` * `threads` * `messages` * `thread_reads` * `file_areas` * `files` * `sessions` * `logs`
Additional tables may be introduced when required by future functionality.
The database should remain simple and understandable rather than attempting to anticipate every future feature.
—
# 5. Users and Access
Users will have a simple access-level system.
Initial conceptual levels:
```text GUEST USER TRUSTED SYSOP ```
The exact numeric representation can be determined during implementation.
Potential permissions include:
* Read local messages * Post local messages * Private messaging * Upload files * Download files * Read packet messages * Post packet messages * Read NTS traffic * Originate NTS traffic * Sysop functions
The system should avoid an elaborate ACL system unless future requirements demonstrate a need for one.
### Packet identity
When packet connectivity is eventually added, an amateur station's AX.25 callsign will serve as its packet identity.
Packet users will not be required to perform a traditional BBS username/password login.
### Telnet identity
When Telnet is eventually added, authentication will be required.
A BBS account may be associated with a callsign while still having a separate username/password for Internet-based access.
### Web administration
The future web administration interface will use authenticated access and provide administrative functions without requiring direct database manipulation.
—
# 6. Message System
Messages will be organized as:
```text Board
|
+-- Thread
|
+-- Message
+-- Message
+-- Message
```
A thread is the primary object displayed to users.
Threads will contain:
* Subject * Board * Creator * Creation date/time * Last activity * Reply count
Messages will contain:
* Author * Thread * Body * Creation date/time * Optional reply relationship
—
# 7. C-Net-Style Thread Reading
Board listings will show threads rather than individual messages.
Example:
```text GENERAL DISCUSSION
1 Packet BBS Development 12 replies Aug 14 10:42
*2 What's on 2 meters? 7 replies Aug 14 09:17
3 New node coming online 3 replies Aug 13 21:03
*4 Old TNC equipment 18 replies Aug 12 18:31 ```
The unread indicator will be an asterisk in the first column.
The message number is shifted one position when the asterisk is displayed.
Headers begin at the first printable column.
—
# 8. Read/Unread Tracking
Read state will be tracked per user and per thread.
The system will maintain the user's last-read message within each thread.
Conceptually:
```text user_id thread_id last_read_message_id last_read_at ```
This allows the BBS to:
* Mark threads containing unread messages. * Show an asterisk beside unread threads. * Resume reading where the user stopped. * Offer “Read New” functionality. * Avoid retransmitting an entire thread over a future low-bandwidth packet connection.
When entering a thread with unread messages, the user may eventually be offered:
```text [R] Read New [A] Read All [L] Last Message ```
—
# 9. Main Menu and Submenus
The BBS will use a single primary menu with hierarchical submenus.
Example:
```text MAIN MENU
[M] Message Center [F] File Areas [U] User Services [N] New Messages [H] Help [Q] Quit ```
Major functions will have their own submenus.
The menu presentation will be external to Python code.
The command engine determines what an option does; the screen/template determines how it looks.
—
# 10. ANSI and Screen System
ANSI support is a core requirement.
The UI system will support, as practical:
* ANSI foreground colors * ANSI background colors * Bold * Underline * Reverse video * Cursor movement * Screen clearing * Box drawing * Symbols * ASCII fallback
Screens will not be hard-coded into Python.
Example structure:
```text screens/
welcome.ans login.ans main.ans messages.ans files.ans help.ans goodbye.ans
```
Screen files may contain variables such as:
```text {bbs_name} {username} {callsign} {message_count} ```
and presentation tags such as:
```text {cyan} {bold} {reset} ```
The renderer will convert these into the appropriate output.
—
# 11. Themes
The screen system should support themes.
Conceptually:
```text themes/
classic/
welcome.ans
main.ans
messages.ans
green/
welcome.ans
main.ans
messages.ans
```
The active theme will be selected through configuration.
Future web administration should allow the sysop to edit and preview screens without manually editing files.
—
# 12. Distribution Classes
Messages will have a distribution classification.
Initial classes:
```text LOCAL PACKET NTS ```
### LOCAL
Local-only BBS traffic.
It must not automatically be forwarded to packet-network peers.
### PACKET
Traffic explicitly designated for packet-network distribution.
### NTS
Traffic intended for the NTS subsystem.
NTS will eventually have additional structure and rules beyond ordinary BBS messages.
—
# 13. Origin and Distribution Are Separate
Messages will track both:
```text origin distribution ```
Examples:
```text Origin: LOCAL Distribution: LOCAL ```
```text Origin: TELNET Distribution: PACKET ```
```text Origin: PACKET Distribution: PACKET ```
This distinction will be important for future forwarding, auditing, and administration.
—
# 14. Telnet Access to Packet/NTS Content
When Telnet support is eventually implemented:
* Packet messages may be read through Telnet. * NTS messages may be read through Telnet. * Packet-originated content does not require special Internet restrictions merely because it arrived over RF. * Telnet-originated traffic destined for packet distribution requires explicit authorization.
A Telnet user should never accidentally cause a local message to be transmitted over RF.
Posting packet-distributed content from Telnet should require:
1. Appropriate account permission. 2. Explicit selection of packet distribution. 3. Confirmation before transmission/queueing.
—
# 15. Packet Forwarding
Packet forwarding will not be part of the initial implementation.
It will be considered after the BBS has reached a stable beta.
The future forwarding subsystem will be separate from the BBS message engine.
Its responsibilities may eventually include:
* Peer configuration * Forwarding queues * Message exchange * Duplicate detection * Routing * Retry handling * Delivery status * Network topology
The BBS should be designed now so that forwarding can be added later without changing the basic message model.
—
# 16. Message IDs and Duplicate Detection
Messages intended for future network distribution should have an identifier suitable for detecting duplicates.
A GUID/UUID or cryptographic hash-based identifier should be considered.
The system should distinguish between:
* Local database ID * Network/global message ID
The local integer database ID should not be assumed to be globally unique.
The exact GUID/hash mechanism will be selected during implementation of the future distribution subsystem.
—
# 17. File Areas
Files will use separate file areas.
Each file area will have its own properties, including future distribution rules.
Files should not automatically be eligible for packet transmission simply because they exist in the BBS.
The architecture must accommodate future specialized transfer methods.
A future idea is QR-code-based file transfers, particularly for Internet-connected clients or local/high-bandwidth use.
QR transfers are explicitly out of scope for v0.1.
—
# 18. Transport Awareness
The BBS session system will eventually identify the transport being used.
Examples:
```text LOCAL TELNET AX25 ```
The UI can use transport information to adapt presentation.
For example, an eventual AX.25 session may use:
* Smaller menus * Reduced decorative output * Pagination * Explicit large-transfer confirmation * Less ANSI artwork * Bandwidth-conscious defaults
Telnet and future specialized clients can provide richer interfaces.
—
# 19. Session State
The BBS will maintain a logical session state.
Example:
```text Main Menu
|
+-- Message Center
|
+-- General
|
+-- Thread 42
|
+-- Message 17
```
Returning from a screen should normally return the user to the appropriate parent menu rather than resetting the entire session.
This will also make future commands such as `WHO` possible.
The eventual `WHO` command may show currently connected users and their current BBS location/activity.
—
# 20. Configuration
Configuration will be external to the Python source.
A configuration file will contain settings such as:
* BBS name * BBS callsign * Location * Time zone * Database location * Active theme * Interface settings * Future Telnet settings * Future packet settings * Logging settings
The exact configuration format will be selected during implementation.
Future web administration should expose appropriate configuration settings without requiring manual file editing.
—
# 21. Logging
Logging is a first-class feature.
The system should record useful operational events such as:
* User creation * Login/logout * Session start/end * Failed authentication * Message creation * Message deletion * File upload/download * Sysop actions * Configuration changes * Future packet connections * Future packet transmissions * Future forwarding activity * Permission changes
Logs should be useful for troubleshooting without becoming an excessive database of everything the user does.
—
# 22. Web Administration — Future
The web administration interface is not required for the first local prototype, but the architecture must accommodate it.
The future web interface should provide:
* User management * Access-level management * Message moderation * Board management * File-area management * File management * Screen/template editing * Theme management * Configuration * Session monitoring * Log viewing * Packet/network administration * Forwarding administration
The web interface should use the same BBS service layer as the other interfaces.
It should not directly manipulate SQLite tables.
—
# 23. Future Internet Client
A specialized Internet client may eventually be developed.
Possible inspiration includes:
* Hotline * KDX * Classic AOL-style client software * Dedicated BBS clients
The client could provide a richer interface while still using the same BBS core and services.
This is explicitly outside the initial scope.
—
# 24. Initial Software Structure
A starting structure may look like:
```text packetbbs/
main.py
core/
users.py
boards.py
threads.py
messages.py
files.py
sessions.py
access.py
database/
database.py
schema.py
ui/
renderer.py
ansi.py
menus.py
screens.py
interfaces/
local.py
screens/
welcome.ans
login.ans
main.ans
messages.ans
files.ans
help.ans
goodbye.ans
themes/
classic/
config/
bbs.toml
data/
bbs.sqlite3
logs/
tests/
```
This is a starting point, not a requirement that every file exist immediately.
Modules should be introduced as functionality is implemented.
—
# 25. Development Strategy
Development will proceed incrementally.
## Phase 1 — Local Prototype
Build only:
* SQLite database * User accounts * Access levels * Local console * ANSI renderer * External screen files * Main menu * Submenus * Boards * Threads * Messages * Read/unread state * Basic file areas * Logging
No network connectivity.
## Phase 2 — Local Beta
Add:
* Better error handling * User preferences * Private messages * Search * Sysop functions * Improved file handling * Screen/theme management * More comprehensive tests * Database backup/restore
## Phase 3 — Telnet
Add:
* Telnet transport * Username/password authentication * Shared BBS accounts * Transport-aware UI * Telnet restrictions for packet/NTS-originating traffic
## Phase 4 — Packet
Add:
* AX.25 transport * Dire Wolf integration * Callsign identity * Packet session handling * Bandwidth-aware UI
## Phase 5 — Packet Distribution
Only after the BBS is stable:
* Network message IDs * Duplicate detection * Forwarding queues * Peer management * Packet forwarding * Delivery tracking
## Phase 6 — Future Features
Potential future work:
* NTS automation * Specialized Internet client * QR-code file transfers * Richer web administration * Advanced packet routing * Additional transport types * Doors/games * Additional BBS integrations
—
# 26. Core Design Rule
The most important architectural rule is:
The BBS should know what a user, message, thread, file, and permission are. It should not need to know how the user connected.
Likewise:
A transport should know how to move data. It should not need to know how a BBS stores messages.
And:
The UI should know how something looks. It should not decide what the BBS is allowed to do.
This separation is what will allow the project to start as a small local BBS and eventually become a packet-radio BBS without requiring a rewrite.
—
# 27. v0.1 Success Criteria
The first version is successful when a user can:
1. Start the BBS locally. 2. Create or log into an account. 3. Navigate a main menu and submenus. 4. Browse message boards. 5. See threaded discussions. 6. Identify unread threads with an asterisk. 7. Read an entire thread. 8. Return later and read only new messages. 9. Post and reply to messages. 10. Browse and use file areas. 11. Receive appropriate access restrictions. 12. See attractive ANSI screens loaded entirely from external files. 13. Have the sysop perform basic administration. 14. Shut down and restart the BBS without losing state. 15. Back up the database easily. 16. Review useful logs.
No radio is required to achieve v0.1.
The result should already feel like a complete, usable BBS before packet connectivity is introduced.