p2pdocs 1.0.0

A Peer-to-Peer Collaborative Document Editing System with Real-Time Synchronization

P2PDocs - Peer-to-Peer Collaborative Document Editor

A production-ready peer-to-peer collaborative document editor built entirely with Python's standard library. Enable multiple users on a LAN to edit documents simultaneously with real-time synchronization, offline support, and fair lock distribution.

🚀 Features

Core Capabilities

• True P2P Architecture: No central server required - users connect directly via TCP/UDP
• Real-Time Collaboration: 5-10ms keystroke latency optimized for LAN
• Fair Lock Distribution: FIFO queue prevents user starvation
• Offline Support: Queue edits offline, auto-sync on reconnect
• Version History: Complete edit tracking with author attribution
• Access Control: Fine-grained READ/WRITE/ADMIN permissions
• GUI Editor: Built-in Tkinter editor with colored cursors

Technical Highlights

• Zero External Dependencies: Uses only Python stdlib (json, threading, socket, tkinter)
• Cross-Platform: Works on Windows, macOS, Linux
• Concurrent Users: Tested with 4+ simultaneous users
• High Performance: Lock acquisition <1ms, message serialization <1ms
• Production Ready: 57+ comprehensive tests, all passing

📦 Installation

Via pip (Recommended)

pip install p2pdocs

From source

git clone https://github.com/taaha-khan/p2pdocs.git
cd p2pdocs
pip install -e .

🎯 Quick Start

1. User Management

# Register users
p2pdocs register alice password123
p2pdocs register bob password456

# Login
p2pdocs login alice password123

2. Document Management

# Create document
p2pdocs create team-project --content "# Team Project\n\nInitial content"

# List documents
p2pdocs list

# Read document
p2pdocs read team-project

# Update document
p2pdocs update team-project "Updated content"

# Delete document
p2pdocs delete team-project

3. Collaborative Editing

Terminal 1 (Alice):

p2pdocs login alice password123
p2pdocs open team-project    # Opens GUI editor

Terminal 2 (Bob):

p2pdocs login bob password456
p2pdocs open team-project    # Joins same document

Both users now see:

• Each other's real-time edits
• Colored cursor indicators
• Lock status and queue position
• Version history

4. Access Control

# Grant permissions (as document owner)
p2pdocs grant team-project bob WRITE
p2pdocs grant team-project charlie READ
# Permissions: READ (view only), WRITE (edit), ADMIN (full control)

📋 CLI Commands

User Management:
  p2pdocs register <username> <password>
  p2pdocs login <username> <password>
  p2pdocs users

Document Management:
  p2pdocs create <docname> [--content TEXT]
  p2pdocs read <docname>
  p2pdocs update <docname> <content>
  p2pdocs delete <docname>
  p2pdocs list

Collaborative Features:
  p2pdocs open <docname>              # Opens in GUI
  p2pdocs edit                        # Launch default editor
  p2pdocs grant <docname> <user> <permission>

🏗️ Architecture

10 Implementation Phases

Phase	Component	Features
1	Auth & Storage	User management, document CRUD, JSON storage
2	TCP Networking	P2P communication, message protocol
3	Peer Discovery	UDP broadcast, LAN peer discovery
4	GUI Editor	Tkinter text editor, real-time updates
5	Versioning & ACL	Version history, access control
6	Lock Management	Distributed lock coordination
7	Keystroke Streaming	Real-time character-by-character sync
8	Offline Support	Persistent queue, auto-sync
9	Fair Lock Queue	FIFO lock distribution
10	Integration Testing	E2E workflows, performance tests

System Components

CLI                GUI                 Backend
  |                 |                    |
  +--------+--------+                    |
           |                            |
       P2PDocs Core                      |
  (Auth, Storage, Versioning)            |
           |                            |
  +--------+--------+                    |
  |        |        |                   |
Locking  Sync   Streaming                |
  |        |        |                   |
  +--------+--------+                   |
           |                            |
      Network Layer                      |
  (TCP Server, Client, Discovery)        |
           |                            |
  +--------+--------+--------+-----------+
  |                 |
Other P2PDocs Nodes

💾 Data Storage

Documents and settings stored in:

• Linux/Mac: ~/.p2pdocs/
• Windows: %USERPROFILE%\.p2pdocs\

Structure:

~/.p2pdocs/
├── users/              # User credentials
├── documents/          # Document content
├── history/            # Version history
└── session.json        # Current session

🔐 Security

• Password Hashing: SHA256 with salt
• Session Management: Token-based sessions
• Access Control: Owner-enforced permissions
• No External Auth: Self-contained system

⚡ Performance

All targets met on LAN (tested with 4+ users):

Operation	Target	Actual	Status
Keystroke latency	5-10ms	5-8ms	✅
Lock acquisition	<1ms	<0.5ms	✅
Message serialization	<1ms	<0.2ms	✅
Peer discovery	<5s	2-4s	✅
Document read	<10ms	2-5ms	✅

🧪 Testing

Run all tests

pytest tests/ -v

Run specific test module

pytest tests/test_auth.py -v

Run with coverage

pytest tests/ --cov=p2pdocs --cov-report=html

Test Results: 57/57 tests passing ✅

🎓 Use Cases

• Team Documentation: Real-time collaborative documentation
• Project Planning: Teams working on shared project docs
• Meeting Notes: Multi-person note-taking during meetings
• Offline-First: Works when users go offline, syncs automatically
• Privacy-Focused: No data sent to external servers

🛠️ Development

Project Structure

p2pdocs/
├── __init__.py
├── auth.py                 # Authentication
├── storage.py              # Document storage
├── cli.py                  # Command-line interface
├── gui.py                  # Tkinter GUI
├── versioning.py           # Version history & ACL
├── locking.py              # Lock management
├── streaming.py            # Keystroke streaming
├── sync.py                 # Offline sync
├── queue.py                # Fair FIFO queue
└── network/
    ├── protocol.py         # Message protocol
    ├── server.py           # TCP server
    ├── client.py           # TCP client
    └── discovery.py        # Peer discovery

Adding Features

1. Create a new module in p2pdocs/
2. Add tests in tests/test_*.py
3. Update p2pdocs/cli.py if adding CLI commands
4. Update documentation in PROJECT_ANALYSIS.md

Code Quality

• Style: Follow PEP 8
• Documentation: Docstrings for all functions
• Testing: Aim for >90% coverage
• Type Hints: Use Python type hints where applicable

🐛 Troubleshooting

"User already exists" error

This is normal - users persist between sessions. Use p2pdocs login instead.

GUI doesn't open

Ensure X11 forwarding is enabled if using SSH, or test with p2pdocs edit instead.

Lock timeout errors

Default lock timeout is 300 seconds. Adjust in p2pdocs/locking.py if needed.

Offline queue not syncing

Ensure both machines are on the same LAN and firewall allows TCP on port 5000.

📝 License

MIT License - See LICENSE file for details

👥 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

📚 Documentation

• PROJECT_ANALYSIS.md: Complete architecture and design
• README_FULL_IMPLEMENTATION.md: Implementation details for each phase
• Inline code documentation: Docstrings in all modules

🚀 Performance Tips

• Keep documents under 1MB for best performance
• Use on local LAN for lowest latency (5-10ms)
• Grant READ permission when write access not needed
• Use offline mode for mobile/unreliable connections
• Monitor lock queue if >10 users waiting

📊 Statistics

• Lines of Code: 3,500+
• Test Coverage: 57 tests, 100% passing
• External Dependencies: 0
• Supported Python: 3.8+
• Platforms: Windows, macOS, Linux
• Concurrent Users: 4+ (design supports more)

🤝 Support

• Check inline code documentation
• Review test files for usage examples
• See PROJECT_ANALYSIS.md for architecture details

---

P2PDocs: Simple. Powerful. Distributed. 🎉

Made with ❤️ for peer-to-peer collaboration