MindGram v3.00 - Changelog & Feature Documentation

Overview

MindGram is a web-based FreeMind mind map viewer with OS/2 Warp 3.0 themed interface. It converts FreeMind .mm files to interactive web diagrams with lazy loading, user management, and collaborative features.

Version 3.00 - Current Release

🎨 OS/2 Warp 3.0 Theme

Complete visual redesign with authentic OS/2 Warp 3.0 aesthetics:

• Purple gradient title bars with classic window chrome
• 3D beveled borders on all UI elements (buttons, windows, inputs)
• Classic gray color scheme (#C0C0C0 window backgrounds)
• OS/2 style components: Checkboxes, radio buttons, scrollbars
• Authentic fonts: System fonts with proper spacing
• Window controls: Minimize, maximize, close buttons
• Press effects: Buttons shift when clicked for tactile feedback

👥 User Management System

Flat-File Based Storage - All data stored as JSON files (no database required):

User Roles

• Admin: Full system access, user management, view/edit all mindmaps
• Editor: Upload mindmaps, manage own mindmaps, generate invites
• Viewers: Access through password-protected mindmaps

Features

• Secure authentication with bcrypt password hashing
• Session management with timeout (1 hour default)
• Login rate limiting: 5 attempts, 15-minute lockout
• CSRF protection on all forms
• Initial setup wizard for first admin account creation

🎟️ Invite-Only Registration

Controlled user onboarding system:

Invite Generation

• Role-based creation: Editors can create editor invites, admins can create any role
• Expiration options: 1, 7, 30, or 90 days
• One-time use tokens: 64-character cryptographically secure tokens
• Clipboard integration: One-click copy for easy sharing

Invite Management

• Status tracking: Active, Used, or Expired badges
• Usage history: See who used each invite and when
• Creator visibility: Admins see all invites, editors see only their own
• Deletion capability: Remove unused invites

🗺️ Mind Map Features

Upload & Conversion

• FreeMind XML parser: Converts .mm files to JSON format
• Title & description: Required metadata for organization
• File size limit: 50MB max per upload
• Ownership tracking: Each map linked to creator account
• Automatic processing: XML validation and node tree building

Viewing & Navigation

• Lazy loading: Root node loads first, children on-demand
• Chunked rendering: 5 nodes at a time for performance
• Progress indicators: Visual feedback during loading
• Two orientations: Horizontal (landscape) and vertical (portrait) modes
• Persistent preferences: Orientation saved in localStorage
• Fullscreen mode: Maximize view to entire screen (ESC to exit)
• Responsive design: Adapts to viewport size with calc(100vh - 200px)

Node Interactions

• Click to expand: Load and display child nodes
• Right-click details: Popup with full content and links
• External links: Open in new tabs with target="_blank"
• Rich content support: HTML content from FreeMind richcontent tags
• Deep linking: Each node has a copy button for direct links
• Auto-navigation: Deep links auto-expand parent nodes and highlight target
• Pulse animation: Highlighted nodes pulse for 3 seconds

Node Copy Feature

• Per-node copy buttons: 📋 button on every node
• URL generation: Creates unique URL with ?node=ID parameter
• Clipboard API: Modern clipboard with fallback for older browsers
• Visual feedback: Button turns green and shows "Copied!"
• Event isolation: Prevents triggering node click when copying

🔒 Password Protection

Secure individual mindmaps:

Protection Features

• Optional passwords: Each mindmap can be protected independently
• Bcrypt encryption: Passwords hashed with industry-standard algorithm
• Session persistence: Verified passwords stored in session
• Password prompts: Beautiful entry form with mindmap details
• Badge indicators: 🔒 icon on protected maps in lists

Edit Capabilities

• Settings page: Edit title, description, and password
• Toggle protection: Enable/disable without re-uploading
• Password updates: Change password or remove protection
• Metadata sync: Updates JSON file and database simultaneously
• Cache invalidation: Clears pruned cache when metadata changes

📊 Mind Map Management

List View (Authenticated Users)

• My Maps page: Personal dashboard for uploaded maps
• Admin view: Admins see all maps across all users
• Rich information: Title, description, creator, date, file size
• Action buttons: View, Copy Link, Edit, Delete
• Permission checks: Only owners and admins can edit/delete
• Delete confirmation: Warns that action cannot be undone
• File cleanup: Removes both JSON and pruned cache files

Edit Page

• Title editing: Update map title (max 200 characters)
• Description editing: Update description (max 500 characters)
• Password management: Enable, disable, or change password
• Visual indicators: Shows creator and creation date
• Validation: Client and server-side validation
• Success feedback: Confirmation messages after updates

🌳 Public Tree View

Browse all mindmaps without login:

Organization

• Grouped by creator: Collapsible sections for each user
• Alphabetical sorting: Creators sorted A-Z
• Newest first: Maps within each creator sorted by date
• Count indicators: Shows number of maps per creator
• Expand/collapse: Click headers to toggle visibility ([-]/[+] icons)

Display Features

• Titles and descriptions: Full metadata visible
• Creation dates: Formatted as "Mon DD, YYYY"
• File sizes: Displayed in KB with one decimal
• Password indicators: 🔒 icon for protected maps
• Direct links: Click title to view map
• Copy buttons: One-click copy for sharing

🔐 Security Features

Authentication

• Bcrypt password hashing: Cost factor optimized for security
• Session management: Server-side session tracking
• Login attempts tracking: IP-based rate limiting
• Auto-lockout: 15 minutes after 5 failed attempts
• Attempt cleanup: Old records removed after 1 hour

Data Protection

• CSRF tokens: Unique tokens for all form submissions
• Token validation: Server-side verification required
• Secure ID generation: random_bytes() instead of uniqid()
• 64-character tokens: Cryptographically secure invite codes
• File locking: Concurrent access protection with flock()

Input Validation

• File type checking: Only .mm files allowed
• File size limits: 50MB max enforced
• XSS prevention: htmlspecialchars() on all output
• Length limits: Title (200), description (500), password (4+)
• Regex validation: ID format validation for mindmap access

📁 File Structure

Data Storage (Flat Files)

data/
├── users.json           # User accounts and profiles
├── invites.json         # Invite tokens and tracking
├── sessions.json        # Active user sessions
├── login_attempts.json  # Failed login tracking
└── mindmaps.json        # Mindmap metadata database

Mindmap Files

mindmaps/
├── [ID].json            # Full mindmap data
└── [ID]_pruned.json     # Cached root-only version

Application Files

• config.php: Centralized constants and configuration
• database.php: Flat-file JSON database with file locking
• auth.php: Authentication and authorization functions
• mindmap-viewer.js: Client-side mindmap rendering class

🎯 User Workflows

For Administrators

1. Setup: Create admin account via setup.php (first time only)
2. Login: Access system with credentials
3. Generate invites: Create invites for new users (admin or editor roles)
4. Manage users: View all users, change roles, reset passwords, deactivate accounts
5. Upload maps: Create new mindmaps with title and description
6. Edit any map: Modify titles, descriptions, passwords for all maps
7. Delete maps: Remove any mindmap from the system
8. Monitor activity: Track uploads, user activity, invite usage

For Editors

1. Login: Access system with credentials
2. Upload maps: Create new mindmaps with metadata
3. Manage own maps: Edit, delete, protect own uploads
4. Generate invites: Create editor-level invite links
5. Share maps: Copy links for public or password-protected sharing
6. Track invites: View own generated invites and usage

For Public Visitors

1. Browse tree: View all public mindmaps at tree.php
2. View maps: Click to view any public mindmap
3. Enter passwords: Access protected maps with password
4. Navigate nodes: Click to expand, right-click for details
5. Copy node links: Share specific nodes with deep links
6. Toggle orientation: Switch between landscape and portrait modes
7. Fullscreen viewing: Maximize map to full screen

🔧 Technical Features

Performance Optimizations

• Lazy loading: Only root node loaded initially
• Chunked processing: 1000 nodes per chunk during upload
• Chunked rendering: 5 nodes per batch when expanding
• File caching: Pruned JSON cached for faster initial loads
• Browser caching: 1-hour cache headers for static content
• Memory cleanup: gc_collect_cycles() and unset() after large operations
• Progress tracking: Real-time progress bars for long operations

Error Handling

• Detailed logging: All operations logged to error.log
• User-friendly messages: Clear error messages for all failure scenarios
• Fallback displays: Error screens when maps fail to load
• Timeout protection: 20-second fallback for unresponsive maps
• Upload validation: Comprehensive checks before processing
• XML validation: LibXML error reporting for invalid files

Browser Compatibility

• Modern clipboard API: Primary method for copy functionality
• Fallback clipboard: execCommand for older browsers
• Visual feedback: Success/failure indicators for all operations
• LocalStorage support: Graceful degradation if unavailable
• Responsive design: Works on desktop and tablet devices

📱 User Interface Components

Navigation

• Consistent headers: OS/2 title bars on all pages
• Role-based menus: Show/hide based on user permissions
• Breadcrumb trails: Clear navigation paths
• Footer links: Global access to tree, upload, login

Forms

• OS/2 styled inputs: Beveled borders and proper spacing
• Radio buttons: Custom styled with OS/2 aesthetic
• Checkboxes: Classic OS/2 checkbox appearance
• Textareas: Multi-line inputs for descriptions
• File uploads: Styled file input buttons
• Submit buttons: 3D beveled with press effect

Feedback

• Success messages: Green boxes with checkmarks
• Error messages: Red boxes with clear text
• Warning messages: Yellow boxes for cautions
• Progress bars: Animated progress with percentage
• Status badges: Color-coded active/inactive/expired indicators
• Copy feedback: Buttons turn green and show "Copied!"

🌐 API & Integration

External Libraries

• jsMind 0.8.8: Core mind mapping engine
• jsMind.draggable-node: Node drag functionality
• Canvas rendering: High-performance visualization

Server Requirements

• PHP 7.4+: Core language requirement
• JSON extension: For data storage
• XMLReader extension: For FreeMind parsing
• Session support: For user authentication
• File write permissions: For uploads and data storage

📊 Data Models

User Record

{
  "id": 1,
  "username": "admin",
  "password": "bcrypt_hash",
  "role": "admin",
  "active": true,
  "created_at": "2025-12-11 10:00:00",
  "last_login": "2025-12-11 15:30:00"
}

Mindmap Record

{
  "id": "32char_hex_id",
  "title": "My Mind Map",
  "description": "Optional description",
  "created_by": 1,
  "created_by_username": "admin",
  "created_at": "2025-12-11 10:00:00",
  "file_path": "mindmaps/32char_hex_id.json",
  "file_size": 102400,
  "password_protected": false,
  "password": null
}

Invite Record

{
  "token": "64char_hex_token",
  "role": "editor",
  "created_by": 1,
  "created_by_username": "admin",
  "created_at": "2025-12-11 10:00:00",
  "expires_at": "2025-12-18 10:00:00",
  "used": false,
  "used_by": null,
  "used_at": null
}

🔄 Mind Map Processing Pipeline

1. Upload: User submits .mm file with title and description
2. Validation: File type, size, and structure checked
3. XML Parsing: XMLReader processes FreeMind format
4. Node Tree Building: Recursive parsing with richcontent support
5. JSON Encoding: Convert to jsMind-compatible format
6. File Storage: Save full JSON to mindmaps/[ID].json
7. Database Entry: Add metadata to mindmaps.json
8. Redirect: Send user to view page

🎥 Viewing Pipeline

1. Request: User visits view.php?id=...
2. Password Check: Verify if map is password-protected
3. Password Prompt: Show form if needed, verify against bcrypt hash
4. Cache Check: Look for [ID]_pruned.json
5. Pruning: If no cache, create root-only version and cache it
6. Rendering: Send pruned JSON to client
7. Lazy Load: Client requests full JSON on node clicks
8. Deep Link: If ?node= parameter exists, auto-navigate to node

🚀 Performance Metrics

• Initial Load: Root node only (~1-5 KB pruned JSON)
• Full Load: On-demand as user explores
• Concurrent Users: File locking prevents corruption
• Upload Processing: ~1-2 seconds for typical 1MB file
• Search/Filter: Client-side instant filtering
• Session Timeout: 1 hour of inactivity

🛡️ Security Best Practices

Implemented

• ✅ Bcrypt password hashing (cost 12)
• ✅ CSRF token protection
• ✅ Login rate limiting
• ✅ Session management with timeout
• ✅ Input validation and sanitization
• ✅ XSS prevention via escaping
• ✅ File type validation
• ✅ Cryptographically secure random tokens
• ✅ File locking for concurrent access

Recommendations

• Configure HTTPS for production
• Set session.cookie_secure = On in php.ini
• Enable session.cookie_httponly = On
• Regular backups of data/ directory
• Monitor error.log for suspicious activity
• Consider max file count limits per user

Version History

v3.00 (2025-12-11)

• Initial release with full feature set
• OS/2 Warp 3.0 themed interface
• User management with invite system
• Password protection for mindmaps
• Public tree view and deep linking
• Node-level sharing with copy buttons
• Lazy loading and performance optimizations

Future Enhancements (Planned)

• 🔄 Real-time collaboration features
• 🎨 Theme customization options
• 📊 Analytics dashboard for admins
• 🔍 Full-text search across all mindmaps
• 📤 Export to PDF/PNG formats
• 🏷️ Tagging and categorization system
• 💬 Comments and annotations on nodes
• 📱 Mobile app companion
• 🔗 Integration with cloud storage (Dropbox, Google Drive)
• 🌍 Multi-language support

Credits

• jsMind: Open-source mind mapping library
• FreeMind: XML format specification
• OS/2 Warp 3.0: Design inspiration
• Development: Custom implementation with PHP, JavaScript, CSS

License

MindGram v3.00 - FreeMind Mind Map Web Viewer All rights reserved.

Last Updated: December 11, 2025 Version: 3.00 Documentation: Complete feature documentation