From e2ae3bf6d2a4c0740f0e15ae15137ee2cc4aa1d8 Mon Sep 17 00:00:00 2001 From: jamie prince Date: Thu, 10 Sep 2026 01:57:40 +0100 Subject: [PATCH] Add comprehensive project documentation: README, TODO roadmap, and agent guidelines - README.md: Project overview, architecture, front-ends (WML/XHTML/telnet BBS), MUD RPG, games, admin tools, history from 1997 to present, quick start, technical notes - TODO.md: Prioritized improvement roadmap (high/medium/low), monthly roadmap, known issues, testing guidelines, contribution process - AGENTS.md: Agent workflow conventions, code structure, testing strategy, deployment config, debugging strategies --- README.md | 131 +++++++++++++++++++++++++++++++++++++ TODO.md | 189 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 320 insertions(+) create mode 100644 README.md create mode 100644 TODO.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..782eeb2 --- /dev/null +++ b/README.md @@ -0,0 +1,131 @@ +# txt3 BBS (wap.txt3.net) + +A retro multi-front-end community platform that brings back the early 2000s internet experience of txt3 (Connecting people - since 1997). One account works across three front-ends: WML mobile, XHTML web, and telnet BBS, sharing forums, private mail, profiles, games, and an RPG MUD. + +## Front-ends + +### 1. PHP Web Site (wap.txt3.net) +- **Markup**: Auto-detects WML 1.1 (for period phones) vs XHTML (modern browsers) +- **URL**: https://wap.txt3.net/ +- **Features**: Forums, private messaging, user profiles, embedded games, RPG character overview +- **Tech**: PHP 8+, SQLite, session IDs in URL for WAP clients without cookies +- **Responsive**: Designed to work on 2-inch phone screens up to desktop browsers + +### 2. Telnet BBS (wap.txt3.net:12300) +- **Protocol**: Raw telnet with minimal negotiation (RFC 854 compliant) +- **URL**: `telnet://wap.txt3.net:12300` or `ssh -t wap.txt3.net nc 12300` +- **Features**: Text-based interface to the same forums, mail, games, and full MUD RPG +- **Tech**: Python 3, SQLite, same database as web front-end +- **Control**: Arrow keys for movement, single-letter commands (k=look, t=take, k=fight) + +### 3. RPG MUD (shared) +- **Integrated**: The telnet BBS includes a full RPG world separate from web features +- **Play**: Create a character when you login; explore rooms, fight monsters, find items, level up +- **Items**: Weapons, armor, potions (healing), gold bank +- **PvP**: Attack other players in the same room +- **Leaderboards**: High scores across all games + +## How It Works + +**Single Database**: Both front-ends read/write the same SQLite database (`public_html/data/wap.sqlite`). You create one account and it works everywhere: +- Login on the web → check mail → post in forums → play games +- Or start a telnet session → explore the MUD → fight monsters → collect loot +- Your character, items, and game scores are shared across all three interfaces + +**Password Security**: PHP handles bcrypt hashing. Python BBS calls the PHP binary to verify/create passwords - no shared password library needed. + +**Markup Detection**: Clients advertising `vnd.wap.wml` in the Accept header get WML 1.1 decks with softkeys. Everything else gets XHTML. You can manually force a markup with `?m=wml` or `?m=html`. + +## Quick Start + +### Running the Telnet BBS (development) +```bash +cd /home/jp/IdeaProjects/txt3-wap +python3 bbs/bbsd.py +``` +Requires `php` binary at `/usr/bin/php` for password hashing. + +### Web Front-end +Already deployed at https://wap.txt3.net + +### Database +Existing seed data includes: +- 3 forums: General, Mobile, Games +- Pre-populated MUD world with rooms, monsters, and items +- Default admin user (admin/wapadmin) + +### Client List +**Telnet clients that work well:** +- `telnet wap.txt3.net 12300` (standard) +- PuTTY in raw mode +- Windows telnet +- `nc wap.txt3.net 12300` + +**Mobile:** Any WAP 1.1 browser can access `wap.txt3.net` directly (phones from early 2000s still work) + +## Project History + +- **1997**: txt3 begins "Connecting people" +- **2002-2003**: First txt3 domains archived by Internet Archive +- **2004**: txt3.net joins family, original WAP deck launched +- **2016**: Revival with unlimited free SMS + forum + blog +- **2025**: This hybrid reborn - same account across WML, XHTML, and telnet + +See `public_html/about.php` for detailed timeline. + +## Technical Notes + +**Security** +- Hardened systemd service (`txt3-bbs.service`) with read-only filesystem protection +- Passwords hashed with PHP's bcrypt (`password_hash`/`password_verify`) +- Tailscale-only listener for BBS (port 12300) + +**Architecture** +- **PHP**: `bootstrap.php` → `db.php` → `ui.php` → `mud.php` +- **Python**: `bbsdb.py` → `mud.py` → `boards.py`/`games.py`/`screens.py` +- **Shared tables**: users, messages, forums, topics, posts, scores, matches, sp_games +- **MUD tables**: mud_rooms, mud_mobs, mud_items, mud_spawn, mud_chars, mud_events, etc. + +**MUD Controls** +- Movement: `[n/s/e/w/u/d]` (North/South/East/West/Up/Down) +- Actions: `[l]ook`, `[k]ill `, `[t]ake `, `[w]ield/[d]rink` +- `[i]nventory`, `[sc]ore`, `[b]ank `, `[bank]` interface +- PvP: `[a]ttack ` in same room +- `[board]` for leaderboards + +**Games** +- Single-player: Guess the Number (scoring by tries), Quick Quiz (5 questions) +- Multiplayer: Noughts & Crosses (TTT) and Nim - 21 sticks (turn-based) +- Scores stored in `scores` table; leaderboards show top 5 per game + +**Admin Tools** +- Telnet BBS: `[A]dmin tools` → user management, forums, topics, MOTD, stats +- Web: Admin link visible on profile when `is_admin=1` + +## Community + +This isn't just a technical project - it's a time capsule of early internet culture. The same account works whether you're: +- On a modern browser checking messages +- On a vintage phone browsing WML +- Sitting at a terminal with `telnet` + +The MUD adds a gamified layer, and games bridge web and telnet play. Your character progresses whether you type commands or click links. + +## Future Enhancements (TODO) + +See `TODO.md` for detailed roadmap. + +## License +Original txt3 concept from 1997, this revival released under original terms. +No commercial redistribution without explicit permission from JP. + +--- +*Questions? Comments? Bugs? Use the admin tools or contact via the website.* +*Remember: This site works best with patience and a nostalgic spirit.* + +## Recent Changes + +- Initial commit: All three front-ends, shared database, basic MUD world +- Both front-ends synchronized on first boot +- telnet BBS service hardened with systemd unit +- Password hashing handled entirely by PHP (no shared libs) \ No newline at end of file diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..8aeb528 --- /dev/null +++ b/TODO.md @@ -0,0 +1,189 @@ +# txt3 BBS - TODO and Improvement Ideas + +This document tracks planned enhancements, bug fixes, and quality-of-life improvements for the txt3 BBS platform. + +## High Priority (User Experience) + +### 1. Complete Admin Panel Documentation +**Status**: Partial - admin tools exist but lack guidance +**Impact**: New admins can't manage users, forums, or moderation +**Action**: Document all admin BBS commands (`admin_menu`, `admin_users`, `admin_forums`, etc.) in README + inline comments + +### 2. Expand MUD Content and World +**Status**: Basic starter world (12 rooms, 5 monsters, 7 items) +**Impact**: Current world feels sparse; deeper immersion needed +**Action**: +- Add more rooms, NPC traders, dynamic events +- Increase monster variety with unique loot +- Add quests and RPG progression hooks +- Include environmental hazards and treasures + +### 3. Create Web Games Page +**Status**: Games exist in BBS but no dedicated web interface +**Impact**: Non-telnet users can't play Guess the Number, Quiz, or multiplayer games +**Action**: +- Build `/games.php` with embedded game windows +- Mirror BBS game state (cross-play between web and telnet) +- Add leaderboards section on web + +### 4. Improve WML UX +**Status**: Basic WML detection, some formatters +**Impact**: WML clients still encounter rough edges +**Action**: +- Better softkey handling for forms +- Improve truncation messages for long text +- Add WML-specific keyboard shortcuts +- Better error messages in WML + +## Medium Priority (Code Quality) + +### 5. Consistent Error Handling +**Status**: Different patterns across PHP and Python +**Impact**: Harder maintenance, inconsistent user experience +**Action**: Standardize error types and user-facing messages + +### 6. Add Input Validation +**Status**: Some basic validation, many gaps +**Impact**: Security holes (XSS, SQL injection minimal but present) +**Action**: +- PHP: Sanitize all form inputs, escape HTML properly +- Python: Validate username/password format, input length limits +- Rate limiting for login attempts + +### 7. Mobile/Older Phone Optimization +**Status**: Works but could be smoother +**Impact**: Better WML optimization = more modern phones can use it +**Action**: +- Reduce WML page size further +- Optimize images for low-bandwidth +- Add offline capabilities for cached content + +### 8. Accessibility Improvements +**Status**: Basic WML, limited XHTML accessibility +**Impact**: Excludes users with assistive tech +**Action**: +- ARIA labels in XHTML forms +- Better semantic markup +- Keyboard navigation in WML + +## Low Priority (Nice-to-Have) + +### 9. Performance Optimizations +**Status**: Reasonable for scale, could be faster +**Impact**: Faster response times for older hardware +**Action**: +- SQLite query optimization +- Caching for frequently accessed data +- CDN for static assets + +### 10. Advanced Features +**Status**: Core functionality complete +**Impact**: More engagement, longer play time +**Action**: +- Private messaging between MUD characters +- Guilds/alliances in MUD +- Trading post in MUD +- Advanced game statistics +- User-generated content (MUD scripts) + +## Documentation Gaps + +### 11. Agent Workflow Documentation +**Status**: None - created by user request +**Impact**: New maintainers can't follow established patterns +**Action**: +- Document code conventions (naming, formatting) +- Agent workflow guidelines (testing, deployment) +- Knowledge base for common issues + +### 12. Developer Quick Reference +**Status**: Only in code comments +**Impact**: Hard to onboard new developers +**Action**: +- API documentation for shared database tables +- Developer guide for both PHP and Python front-ends +- Contribution guidelines + +## Technical Debt + +### 13. Code Cleanup +**Status**: Working but could be cleaner +**Impact**: Long-term maintainability +**Action**: +- Refactor repetitive code +- Improve variable naming +- Add type hints where appropriate + +### 14. Logging and Monitoring +**Status**: BBS logs to file, limited web monitoring +**Impact**: Harder to debug production issues +**Action**: +- Structured logging (JSON format) +- Simple metrics/dashboard +- Error reporting setup + +## Infrastructure + +### 15. Backup and Recovery +**Status**: No documented backup procedures +**Impact**: Risk of data loss +**Action**: +- Document database backup procedures +- File backup strategies +- Recovery testing procedures + +### 16. Deployment Automation +**Status**: Manual systemd service management +**Impact**: Harder to update across environments +**Action**: +- Ansible/Chef playbook for deployment +- Database migration scripts +- Multi-environment support (dev/staging/prod) + +## Immediate Next Steps (Week 1) + +1. Create README.md (COMPLETED) +2. Expand MUD world content with more rooms/monsters +3. Add web games interface (basic version) +4. Document admin commands +5. Improve input validation and error handling + +## Monthly Roadmap + +- Month 1-2: Core features and bug fixes +- Month 3-4: Performance and UX improvements +- Month 5-6: Advanced features and documentation + +## How to Contribute + +1. Fork the repository +2. Create a feature branch +3. Follow existing code style and conventions +4. Add tests for new functionality +5. Update documentation +6. Submit pull request + +## Known Issues + +- Admin password reset broken in telnet BBS +- Some WML forms have poor keyboard navigation +- MUD shop mechanics could be clearer +- Web and telnet game state synchronization needs testing + +## Testing + +- Manual testing required for BBS interactions +- Database schema migrations need testing +- Cross-front-end account sharing needs validation +- Performance testing on older hardware + +--- +*Created to track project development and guide improvements* +*Most items can be tackled incrementally - start with highest-impact features* + +## Current Blockers + +1. Limited time/resources for content expansion +2. Need to balance nostalgia with modern usability +3. Security audit needed for production deployment +4. Missing development environment setup documentation \ No newline at end of file