====== 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.