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
This commit is contained in:
131
README.md
Normal file
131
README.md
Normal file
@ -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<monster>=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 <monster>`, `[t]ake <item>`, `[w]ield/[d]rink`
|
||||||
|
- `[i]nventory`, `[sc]ore`, `[b]ank <amt>`, `[bank]` interface
|
||||||
|
- PvP: `[a]ttack <player>` 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)
|
||||||
189
TODO.md
Normal file
189
TODO.md
Normal file
@ -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
|
||||||
Reference in New Issue
Block a user