github/torrentpier
1
0
Fork 0
mirror of https://github.com/torrentpier/torrentpier synced 2025-07-05 12:36:12 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

feat: add comprehensive documentation for legacy TorrentPier system (#2023)
Some checks are pending
Deploy Documentation to GitHub Pages / Build Documentation (push) Waiting to run
Details
Deploy Documentation to GitHub Pages / Deploy to GitHub Pages (push) Blocked by required conditions
Details

Browse source 
- Introduced multiple new markdown files detailing the legacy TorrentPier v2.x system, including an overview, database schema analysis, database relationships, integration flow analysis, and attachment system complexity.
- These documents serve as a reference for the ongoing modernization effort, highlighting areas of complexity and providing insights for migration strategies.
- The goal is to ensure feature parity in the new system while simplifying unnecessary complexities from the legacy architecture.
This commit is contained in:
Yury Pikhtarev 2025-07-01 14:17:53 +04:00 • committed by GitHub
parent 48a17c47c6
commit ccf2400450
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 969 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/docs/legacy/_category_.json Normal file
View file

@ -0,0 +1,10 @@
{
"label": "Legacy System",
"position": 6,
"link": {
"type": "generated-index",
"title": "Legacy System Documentation",
"description": "Documentation and analysis of the legacy TorrentPier v2.x system that is being modernized with Laravel.",
"keywords": ["legacy", "torrentpier", "migration"]
}
}

300
docs/docs/legacy/attachment-system-complexity.md Normal file
View file

@ -0,0 +1,300 @@
---
sidebar_position: 5
title: Attachment System Complexity
---
# Attachment System Analysis
## Overview
The legacy TorrentPier attachment system is severely over-engineered for a modern torrent tracker. This document catalogs the unnecessary complexity and proposes a dramatically simplified approach.
## Current Legacy Complexity: 7 Tables
### 1. `bb_attachments_desc` - File Metadata Storage
```sql
attach_id MEDIUMINT UNSIGNED (Primary Key)
physical_filename VARCHAR(255) -- Server filename (abc123.torrent)
real_filename VARCHAR(255) -- Original filename (movie.torrent)
download_count MEDIUMINT UNSIGNED -- Download statistics
comment VARCHAR(255) -- File description
extension VARCHAR(100) -- File extension
mimetype VARCHAR(100) -- MIME type
filesize BIGINT -- Size in bytes
filetime INT -- Upload timestamp
thumbnail BOOLEAN -- Has thumbnail
tracker_status BOOLEAN -- Is torrent file
```
**Purpose**: Stores metadata for every uploaded file
**Complexity**: Supports ANY file type with extensive metadata
### 2. `bb_attachments` - File-to-Post Links
```sql
attach_id MEDIUMINT UNSIGNED -- Links to bb_attachments_desc
post_id MEDIUMINT UNSIGNED -- Links to bb_posts
user_id_1 MEDIUMINT -- Uploader ID
```
**Purpose**: Links files to forum posts
**Complexity**: Supports multiple attachments per post across all file types
### 3. `bb_extensions` - File Extension Validation
```sql
ext_id MEDIUMINT UNSIGNED (Primary Key)
group_id MEDIUMINT UNSIGNED -- Links to bb_extension_groups
extension VARCHAR(100) -- File extension (jpg, png, torrent)
comment VARCHAR(100) -- Description
```
**Purpose**: Validates allowed file extensions
**Current Extensions**: 40+ different file types supported
```text
Images: gif, png, jpeg, jpg, webp, avif, bmp
Archives: gtar, gz, tar, zip, rar, ace, 7z
Text: txt, c, h, cpp, hpp, diz, m3u
Documents: xls, doc, dot, pdf, ai, ps, ppt
Media: rm (RealMedia)
Torrents: torrent
```
### 4. `bb_extension_groups` - File Type Categories
```sql
group_id MEDIUMINT (Primary Key)
group_name VARCHAR(20) -- "Images", "Archives", "Torrents"
cat_id TINYINT -- Category type
allow_group BOOLEAN -- Is group enabled
download_mode TINYINT UNSIGNED -- How files are served
upload_icon VARCHAR(100) -- Icon for file type
max_filesize BIGINT -- Size limit per group
forum_permissions TEXT -- Complex permission matrix
```
**Current Groups**: Images, Archives, Plain text, Documents, Real media, Torrent
**Purpose**: Categorizes file types with different rules per category
### 5. `bb_attachments_config` - Complex Configuration
```sql
config_name VARCHAR(155) -- Configuration key
config_value VARCHAR(255) -- Configuration value
```
**Current Settings**: 14 different configuration options
```text
upload_dir -- Upload directory path
max_filesize -- Global size limit
attachment_quota -- Total quota limit
max_attachments -- Files per post limit
max_attachments_pm -- Files per PM limit
disable_mod -- Disable system
allow_pm_attach -- Allow PM attachments
img_display_inlined -- Show images inline
img_max_width/height -- Image dimension limits
img_link_width/height -- Thumbnail dimensions
img_create_thumbnail -- Auto-thumbnail generation
img_min_thumb_filesize -- Thumbnail threshold
```
### 6. `bb_attach_quota` - User/Group Quotas
```sql
user_id MEDIUMINT UNSIGNED -- User ID (or 0 for group)
group_id MEDIUMINT UNSIGNED -- Group ID (or 0 for user)
quota_type SMALLINT -- Quota type identifier
quota_limit_id MEDIUMINT UNSIGNED -- Links to bb_quota_limits
```
**Purpose**: Different attachment quotas per user or group
**Complexity**: Supports individual user quotas AND group-based quotas
### 7. `bb_quota_limits` - Quota Definitions
```sql
quota_limit_id MEDIUMINT UNSIGNED (Primary Key)
quota_desc VARCHAR(20) -- "Low", "Medium", "High"
quota_limit BIGINT UNSIGNED -- Limit in bytes
```
**Current Quotas**: Low (256KB), Medium (10MB), High (15MB)
**Purpose**: Reusable quota limit definitions
## Complexity Analysis
### Total Lines of Code for Attachment System
- **Database Schema**: ~200 lines across 7 tables
- **PHP Classes**: ~2000+ lines in `attach_mod/` directory
- **Admin Interface**: ~500 lines for attachment management
- **Configuration Options**: 14 different settings
- **Permission Matrix**: Complex forum-specific permissions per file type
### Features That Add Complexity
#### 1. Multi-File Type Support
**Current**: Supports 6 different file categories with 40+ extensions
**Reality**: Modern torrent trackers only need torrents + optional archives
#### 2. Advanced Image Handling
**Current**: Automatic thumbnail generation, size limits, inline display
**Reality**: Images aren't needed for torrent files
#### 3. Complex Quota System
**Current**: Individual user quotas + group quotas + file type quotas
**Reality**: Simple disk space limit is sufficient
#### 4. Download Mode Options
**Current**: Multiple ways to serve files (inline, download, etc.)
**Reality**: Torrents should always download, archives can be simple download
#### 5. Permission Matrix
**Current**: Per-forum, per-group, per-file-type permissions
**Reality**: Simple upload/download permissions are sufficient
#### 6. Advanced Statistics
**Current**: Download counting, usage tracking per file
**Reality**: Not needed for torrent files (tracker handles stats)
## Real-World Usage Analysis
### What Actually Gets Used
Based on typical torrent tracker usage:
- **95%+ of attachments**: `.torrent` files
- **5% of attachments**: `.zip`/`.rar` archives (sample files, subtitles)
- **Less than 1% of attachments**: Everything else
### What Features Are Actually Needed
1. **Store torrent files**: Upload, store, serve `.torrent` files
2. **Basic archives**: Optional support for `.zip`, `.rar`, `.7z`
3. **Simple validation**: Check file extensions and basic size limits
4. **Basic security**: Virus scanning, extension validation
5. **Storage management**: Clean up old files
### What Features Are NOT Needed
1. **Image handling**: Thumbnails, inline display, dimension limits
2. **Document support**: PDF, Office files, etc.
3. **Media support**: RealMedia, etc.
4. **Complex quotas**: Per-user, per-group quota matrices
5. **Advanced permissions**: Per-forum, per-type permission systems
6. **Download statistics**: Files downloaded X times
7. **Multiple download modes**: Inline vs download serving
## Proposed Modern Simplification
### Reduce number of Tables
#### `attachments` (replaces 3 legacy tables)
```sql
id BIGINT UNSIGNED (Primary Key)
post_id BIGINT UNSIGNED -- Links to posts
user_id BIGINT UNSIGNED -- Uploader
filename VARCHAR(255) -- Original filename
stored_filename VARCHAR(255) -- Server filename (UUID-based)
file_type ENUM('torrent', 'archive') -- Simple type
file_size BIGINT UNSIGNED -- Size in bytes
mime_type VARCHAR(100) -- MIME type
uploaded_at TIMESTAMP -- Upload time
downloads INT UNSIGNED DEFAULT 0 -- Simple download counter
INDEX (post_id)
INDEX (user_id)
INDEX (file_type)
```
### Simplified Configuration (Laravel Config)
```php
// config/attachments.php
return [
'allowed_types' => ['torrent', 'zip', 'rar', '7z'],
'max_size' => 50 * 1024 * 1024, // 50MB
'storage_path' => env('ATTACHMENT_STORAGE', 'storage/app/attachments'),
'virus_scan' => env('ATTACHMENT_VIRUS_SCAN', false),
];
```
### Simple File Handling (Laravel)
```php
// Single service class handles all attachment logic
class AttachmentService
{
public function store(UploadedFile $file, Post $post): Attachment
public function validateTorrent(UploadedFile $file): array
public function serve(Attachment $attachment): Response
public function delete(Attachment $attachment): bool
}
```
## Comparison: Legacy vs Modern
| Aspect | Legacy System | Modern System |
|---------------------|--------------------------------|-----------------------------------|
| **File Types** | 40+ extensions in 6 categories | 4 extensions (torrent + archives) |
| **Configuration** | 16 database settings | 4 config file settings |
| **Quota System** | User + Group + Type quotas | Simple size limit |
| **Permissions** | Complex matrix | Simple upload/download |
| **Code Complexity** | 2500+ lines | ~200 lines |
| **Admin Interface** | Full management system | Minimal configuration |
| **Performance** | Multiple table joins | Simple queries |
## Benefits of Simplification
### Development Benefits
- **90% less code** to maintain
- **Simple testing** - only 2 file types to test
- **Easy debugging** - minimal moving parts
- **Fast development** - no complex permission logic
### Performance Benefits
- **Smaller codebase** - faster loading
- **Less memory usage** - simpler object structure
- **Better caching** - fewer cache keys needed
### User Experience Benefits
- **Faster uploads** - less validation overhead
- **Simpler interface** - fewer configuration options
- **More reliable** - fewer things that can break
- **Better performance** - optimized for actual usage
### Security Benefits
- **Smaller attack surface** - fewer file types supported
- **Easier validation** - only validate what's needed
- **Simpler permissions** - fewer permission bugs
- **Better auditing** - simpler audit trail
## Conclusion
The legacy attachment system is a textbook example of over-engineering. It supports dozens of file types and complex features that simply aren't needed for a torrent tracker.
By reducing number of tables and eliminating 90% of the features, we can create a system that is:
- **Simpler to understand and maintain**
- **Faster and more reliable**
- **Focused on actual user needs**
- **Easier to secure and audit**
The simplified system will handle 99%+ of real-world usage while being dramatically easier to build and maintain.

229
docs/docs/legacy/database-relationships.md Normal file
View file

@ -0,0 +1,229 @@
---
sidebar_position: 3
title: Database Relationships
---
# Database Relationships & Entity Dependencies
## Overview
This document maps all key relationships in the TorrentPier database schema, identifying primary keys, foreign keys, and data dependencies. This analysis is crucial for designing the modern Laravel schema with proper Eloquent relationships.
## Core Entity Relationship Diagram
```text
Users ──┐
│
├── Topics ──── Posts ──── Attachments ──── Files
│ │ │ │
│ │ └── PostText └── AttachmentMetadata
│ │
│ └── Torrents ──── TrackerPeers
│ │ │
│ └── TorrentStats └── UserStats
│
├── Groups ──── Permissions
│
└── Sessions
```
## Primary Entities & Their Relationships
### 1. Forum Hierarchy
```text
Categories (1:many) Forums (1:many) Topics (1:many) Posts
│ │ │ │
└── forum_id └── topic_id └── post_id └── PostText (1:1)
```
**Key Relationships:**
- `bb_categories.cat_id` → `bb_forums.cat_id`
- `bb_forums.forum_id` → `bb_topics.forum_id`
- `bb_topics.topic_id` → `bb_posts.topic_id`
- `bb_posts.post_id` → `bb_posts_text.post_id`
### 2. User System
```text
Users (many:many) Groups (1:many) Forums
│ │ │
└── user_id └── group_id └── Permissions
```
**Key Relationships:**
- `bb_users.user_id` → `bb_user_group.user_id`
- `bb_groups.group_id` → `bb_user_group.group_id`
- `bb_groups.group_id` → `bb_auth_access.group_id`
- `bb_forums.forum_id` → `bb_auth_access.forum_id`
### 3. Torrent Integration (Critical Path)
```text
Topics (1:1) Torrents (1:1) AttachmentFiles
│ │ │
└── topic_id └── attach_id └── TorrentFile
│
└── TrackerPeers (1:many)
```
**Critical Relationships:**
- `bb_topics.topic_id` = `bb_bt_torrents.topic_id` **(1:1 - Core Integration)**
- `bb_bt_torrents.attach_id` = `bb_attachments_desc.attach_id` **(1:1)**
- `bb_posts.post_id` = `bb_attachments.post_id` **(1:many)**
- `bb_attachments.attach_id` = `bb_attachments_desc.attach_id` **(1:1)**
### 4. Tracker System
```text
Torrents (1:many) TrackerPeers
│ │
└── topic_id └── user_id → Users
```
**Key Relationships:**
- `bb_bt_torrents.topic_id` → `bb_bt_tracker.topic_id`
- `bb_users.user_id` → `bb_bt_tracker.user_id`
- `bb_users.user_id` → `bb_bt_users.user_id`
## Data Flow Dependencies
### Torrent Posting Flow
```text
1. User Authentication
bb_users.user_id
2. Forum Selection
bb_categories → bb_forums (permissions check)
3. Topic Creation
bb_topics.topic_id (generated)
4. Post Creation
bb_posts → bb_posts_text
5. File Upload
bb_attachments_desc (torrent file)
bb_attachments (link to post)
6. Torrent Registration
bb_bt_torrents (links everything together)
7. Tracker Activation
bb_bt_tracker (peer monitoring begins)
```
### Dependencies for Deletion
```text
Delete Torrent:
1. Remove tracker peers: bb_bt_tracker
2. Remove torrent stats: bb_bt_*stat tables
3. Remove torrent record: bb_bt_torrents
4. Remove attachment files: bb_attachments_desc, bb_attachments
5. Remove posts: bb_posts_text, bb_posts
6. Remove topic: bb_topics
```
## Orphaned Data Prevention
### Current Issues in Legacy
- No foreign key constraints allow orphaned records
- Manual cleanup required via cron jobs
- Inconsistent data possible
### Modern Solution
```sql
-- Cascade deletions where appropriate
ON DELETE CASCADE for content dependencies
ON DELETE SET NULL for optional references
ON DELETE RESTRICT for critical business data
```
## Complex Relationships
### Many-to-Many: Users ↔ Groups
```text
bb_users ←→ bb_user_group ←→ bb_groups
```
### Many-to-Many: Users ↔ Tracked Torrents
```text
bb_users ←→ bb_bt_tracker ←→ bb_bt_torrents
```
### Polymorphic: Attachments
```text
bb_attachments can belong to:
- bb_posts (forum attachments)
- bb_privmsgs (private message attachments)
```
## Denormalization in Legacy Schema
### Forum Statistics
```text
bb_forums.forum_posts -- Cached from bb_posts count
bb_forums.forum_topics -- Cached from bb_topics count
bb_topics.topic_replies -- Cached from bb_posts count
bb_topics.topic_views -- Cached/updated separately
```
### Torrent Statistics
```text
bb_bt_torrents.complete_count -- Cached completion count
bb_bt_torrents.seeder_last_seen -- Cached timestamp
bb_users.user_posts -- Cached post count
```
## Modern Laravel Relationships
### Eloquent Model Relationships
```php
// Topic Model
public function posts() { return $this->hasMany(Post::class); }
public function torrent() { return $this->hasOne(Torrent::class); }
public function forum() { return $this->belongsTo(Forum::class); }
// Torrent Model
public function topic() { return $this->belongsTo(Topic::class); }
public function peers() { return $this->hasMany(TrackerPeer::class); }
public function attachment() { return $this->belongsTo(Attachment::class); }
// User Model
public function posts() { return $this->hasMany(Post::class, 'poster_id'); }
public function torrents() { return $this->hasMany(Torrent::class, 'poster_id'); }
public function trackerStats() { return $this->hasOne(TrackerUser::class); }
```
### Recommended Constraints
```sql
-- Strict constraints for data integrity
FOREIGN KEY (topic_id) REFERENCES topics(id) ON DELETE CASCADE
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE RESTRICT
FOREIGN KEY (forum_id) REFERENCES forums(id) ON DELETE RESTRICT
-- Indexes for performance
INDEX (topic_id, user_id) for tracker queries
INDEX (forum_id, topic_time) for forum browsing
INDEX (info_hash) for tracker announces
```
## Summary
The legacy schema has complex implicit relationships that need to be formalized with proper foreign key constraints in the modern Laravel implementation. The core `topic_id` integration between forum and tracker systems must be preserved while adding proper referential integrity.
Key improvements needed:
1. **Add foreign key constraints** for data integrity
2. **Remove buffer table dependencies** (replace with Laravel Queues)
3. **Implement proper cascading deletes** for cleanup
4. **Use Laravel conventions** for relationship naming and structure

229
docs/docs/legacy/integration-flow-analysis.md Normal file
View file

@ -0,0 +1,229 @@
---
sidebar_position: 4
title: Integration Flow Analysis
---
# Integration Flow Analysis
## Overview
This document provides a detailed analysis of how the forum system integrates with the BitTorrent tracker in TorrentPier, mapping the complete data flow from user posting a torrent to tracker monitoring.
## Core Architecture Principle
**TorrentPier = Forum + BitTorrent Tracker as One Integrated System**
Unlike separate forum and tracker applications, TorrentPier tightly integrates both:
- **Forum posts contain media descriptions** (title, plot, technical details, etc.)
- **Tracker tables handle only BitTorrent protocol data** (info_hash, peers, statistics)
- **Integration point**: `topic_id` links forum topics to tracker entries
## Complete Data Flow: Posting a Torrent
### Step 1: User Creates Forum Topic
```sql
INSERT INTO bb_topics (
topic_id, -- Generated ID
forum_id, -- Which forum section (Movies, TV, etc.)
topic_title, -- "Movie Name (2023) [1080p BluRay]"
topic_poster, -- User ID
topic_time, -- Timestamp
topic_dl_type -- Marks as download/torrent topic
);
```
**Purpose**: The topic title contains the primary media identification
**Example**: "The Matrix (1999) [1080p BluRay x264-GROUP]"
### Step 2: User Writes Detailed Post
```sql
INSERT INTO bb_posts (
post_id, -- Generated ID
topic_id, -- Links to topic
forum_id, -- Same as topic
poster_id, -- User ID
post_time -- Timestamp
);
INSERT INTO bb_posts_text (
post_id, -- Links to post
post_text -- Rich media description with BBCode
);
```
**Purpose**: The post content contains detailed media information:
- Plot synopsis
- Cast and crew
- Technical specifications (codec, resolution, etc.)
- Screenshots
- File listing
- Any media metadata the user wants to include
### Step 3: User Attaches Torrent File
```sql
INSERT INTO bb_attachments_desc (
attach_id, -- Generated ID
physical_filename, -- "abc123.torrent" (on server)
real_filename, -- "movie.torrent" (original name)
filesize, -- Size in bytes
filetime, -- Upload timestamp
tracker_status -- Marks as torrent file
);
INSERT INTO bb_attachments (
attach_id, -- Links to attachment metadata
post_id, -- Links to the post
user_id_1 -- Uploader ID
);
```
**Purpose**: Stores the actual .torrent file that contains BitTorrent metadata
### Step 4: System Creates Tracker Entry
```sql
INSERT INTO bb_bt_torrents (
topic_id, -- Links to forum topic (KEY INTEGRATION)
post_id, -- Links to first post
attach_id, -- Links to torrent file
poster_id, -- Original uploader
forum_id, -- Forum section
info_hash, -- SHA-1 from torrent file
info_hash_v2, -- SHA-256 for v2 torrents
size, -- Total size from torrent
reg_time, -- Registration timestamp
tor_status, -- Moderation status
complete_count, -- Number of completed downloads
-- Additional tracker statistics
);
```
**Purpose**: Creates tracker entry that links the forum topic to BitTorrent tracking
### Step 5: Tracker Begins Monitoring
When BitTorrent clients announce, data goes into:
```sql
INSERT INTO bb_bt_tracker (
topic_id, -- Links back to forum topic
peer_id, -- BitTorrent peer ID
user_id, -- Authenticated user
ip, -- Client IP
port, -- Client port
uploaded, -- Bytes uploaded
downloaded, -- Bytes downloaded
-- Real-time peer data
);
```
## Key Integration Relationships
### Primary Links
```text
bb_topics.topic_id = bb_bt_torrents.topic_id (1:1)
bb_posts.topic_id = bb_topics.topic_id (1:many)
bb_attachments.post_id = bb_posts.post_id (1:many)
bb_bt_torrents.attach_id = bb_attachments_desc.attach_id (1:1)
bb_bt_tracker.topic_id = bb_bt_torrents.topic_id (1:many)
```
### Data Flow Visualization
```text
┌─────────────────┐
│ bb_topics │ ← Media title/description container
│ topic_id: 123 │
└─────────────────┘
│
├─────────────────┐
│ │
┌─────────────────┐ ┌─────────────────┐
│ bb_posts │ │ bb_bt_torrents │ ← BitTorrent tracking
│ topic_id: 123 │ │ topic_id: 123 │
│ post_id: 456 │ │ attach_id: 789│
└─────────────────┘ └─────────────────┘
│ │
┌─────────────────┐ ┌─────────────────┐
│bb_posts_text │ │bb_attachments │
│ post_id: 456 │ │ attach_id: 789 │
│ "Movie details" │ │ post_id: 456 │
└─────────────────┘ └─────────────────┘
│
┌─────────────────┐
│bb_attachments │ ← Torrent file storage
│_desc │
│ attach_id: 789 │
│ "movie.torrent" │
└─────────────────┘
```
## User Experience Flow
### Posting a Torrent
1. **User selects forum** (Movies, TV Shows, Games, etc.)
2. **User creates topic** with descriptive title
3. **User writes post** with media details, screenshots, file listing
4. **User uploads .torrent file** as attachment
5. **System processes torrent** and creates tracker entry
6. **Torrent appears in forum** and tracker simultaneously
### Viewing a Torrent
1. **User sees topic in forum** with standard forum display
2. **Special markers** indicate it's a torrent topic
3. **Torrent information displayed** alongside post content:
- Download stats (seeders/leechers)
- File listing
- Download button/magnet link
4. **Comments/discussion** continue as normal forum posts
### Downloading a Torrent
1. **User clicks download** in forum topic
2. **System serves .torrent file** from attachments
3. **BitTorrent client announces** to tracker
4. **Tracker updates statistics** linked to forum topic
## Critical Design Insights
### 1. Media Metadata Storage
- **NOT in tracker tables** - these handle only BitTorrent protocol data
- **IN forum content** - topic titles and post descriptions
- **User-generated** - community provides rich descriptions
- **Flexible format** - BBCode allows formatted descriptions
### 2. Integration Benefits
- **Single user experience** - forum and tracker feel like one system
- **Community curation** - users discuss and improve content descriptions
- **Moderation unified** - same permissions for forum and tracker
### 3. Technical Separation
- **Forum tables** handle content and discussion
- **Tracker tables** handle BitTorrent protocol specifics
- **Attachment tables** bridge the two systems
- **Clear boundaries** make system maintainable
## Modern Laravel Implementation Strategy
### Maintain Integration
- Keep `topic_id` as primary integration key
- Preserve forum-centric user experience
- Maintain unified moderation workflow
### Simplify Implementation
- Use Laravel relationships instead of complex foreign key management
- Implement tracker updates via Laravel Queues
- Use Eloquent models to encapsulate business logic
### Improve Performance
- Cache tracker statistics
- Use background jobs for statistics updates
- Optimize database queries with proper indexing
## Summary
The forum-tracker integration in TorrentPier is its core strength. Media metadata lives in user-generated forum content while BitTorrent protocol data is handled separately. The `topic_id` serves as the integration key that links rich media descriptions to technical tracking data.
This architecture should be preserved in the Laravel rewrite while simplifying the implementation using modern frameworks and patterns.

46
docs/docs/legacy/overview.md Normal file
View file

@ -0,0 +1,46 @@
---
sidebar_position: 1
title: Overview
---
# System Overview
## Introduction
This section contains comprehensive documentation and analysis of the legacy TorrentPier v2.x system. These documents serve as reference material for the ongoing modernization effort to rebuild the application using Laravel and modern web technologies.
## Purpose
The legacy documentation helps us:
- Understand the existing system architecture and data flows
- Identify areas of unnecessary complexity
- Plan migration strategies
- Ensure feature parity in the new system
- Learn from past design decisions
## Key Documents
### [Database Schema Analysis](./schema-analysis)
A comprehensive analysis of all 58 tables in the legacy database, organized by functional domain with modernization recommendations.
### [Database Relationships](./database-relationships)
Detailed mapping of all entity relationships, foreign keys, and data dependencies crucial for designing proper Eloquent relationships.
### [Integration Flow Analysis](./integration-flow-analysis)
Complete data flow documentation showing how the forum system integrates with the BitTorrent tracker.
### [Attachment System Complexity](./attachment-system-complexity)
Analysis of the over-engineered attachment system and proposals for dramatic simplification.
## Migration Philosophy
The goal is not to replicate the legacy system exactly, but to:
1. **Preserve core functionality** - Maintain the essential forum-tracker integration
2. **Simplify complexity** - Remove unnecessary features and over-engineering
3. **Modernize architecture** - Use Laravel's built-in features instead of custom solutions
4. **Improve user experience** - Create a cleaner, more intuitive interface
## Key Insights from Legacy Analysis
1. **Over-Engineering**: Many systems (attachments, permissions, caching) are unnecessarily complex
2. **Buffer Tables**: Performance optimizations through buffer tables can be replaced with modern caching and queues

155
docs/docs/legacy/schema-analysis.md Normal file
View file

@ -0,0 +1,155 @@
---
sidebar_position: 2
title: Database Schema Analysis
---
# Database Schema Analysis
## Overview
This document provides a comprehensive analysis of the legacy TorrentPier database schema, identifying all tables organized by functional domain, their relationships, and recommendations for modernization in the Laravel rewrite.
**Key Architecture Insight**: TorrentPier is a **forum-integrated BitTorrent tracker** where media content descriptions are stored in forum posts, and the tracker system links directly to forum topics via `topic_id`. This tight integration means that media metadata should live in the forum content, not the torrent tracking tables.
## Table Inventory by Functional Domain
### 1. Forum System (Core Content)
| Table | Purpose | Replacement |
|-----------------|-------------------------------------|----------------------------|
| `bb_categories` | Forum categories | Keep with improvements |
| `bb_forums` | Individual forums within categories | Keep with improvements |
| `bb_topics` | Forum topics | Keep with improvements |
| `bb_posts` | Individual posts in topics | Keep with improvements |
| `bb_posts_text` | Post content storage | **Merge into posts table** |
### 2. BitTorrent Tracker System
| Table | Purpose | Replacement |
|-----------------------|------------------------------|--------------------------------------------|
| `bb_bt_torrents` | Core torrent registry | Keep with improvements |
| `bb_bt_tracker` | Active peer tracking | Keep with improvements |
| `bb_bt_users` | User tracker statistics | Keep with improvements |
| `bb_bt_tracker_snap` | Tracker statistics snapshots | **Replace with Laravel Queues** |
| `bb_bt_dlstatus_snap` | Download status snapshots | **Replace with Laravel Queues** |
| `bb_bt_dlstatus` | Download status tracking | **Merge into torrent statistics per user** |
| `bb_bt_torstat` | Torrent statistics per user | Keep with improvements |
| `bb_bt_tor_dl_stat` | Torrent download statistics | **Merge into torrent statistics per user** |
| `bb_bt_last_torstat` | Last torrent statistics | **Replace with Laravel Queues** |
| `bb_bt_last_userstat` | Last user statistics | **Replace with Laravel Queues** |
| `bb_bt_torhelp` | Torrent help system | **Replace with Laravel Queues** |
| `bb_bt_user_settings` | User tracker preferences | **Merge into user settings** |
### 3. Attachment System
| Table | Purpose | Replacement |
|-------------------------|-----------------------------------------------|---------------------------------|
| `bb_attachments` | Links attachments to posts | Keep with improvements |
| `bb_attachments_desc` | Attachment metadata | Keep with improvements |
| `bb_extensions` | File extension validation | **Remove** |
| `bb_extension_groups` | Extension categories (Images, Archives, etc.) | **Remove** |
| `bb_attachments_config` | Complex attachment configuration | **Replace with Laravel Config** |
| `bb_attach_quota` | User/group attachment quotas | **Remove** |
| `bb_quota_limits` | Quota limit definitions | **Remove** |
**Current Complexity**: Supports multiple file type categories with complex permissions, quotas, and download modes
**Modern Approach**: Only support `.torrent` files and basic archives (`.zip`, `.rar`, `.7z`)
### 4. User Management
| Table | Purpose | Replacement |
|-----------------------|---------------------------|-------------------------------------|
| `bb_users` | User accounts | Keep with improvements |
| `bb_groups` | User groups | Keep with role-based permissions |
| `bb_user_group` | User groups memberships | Keep with improvements |
| `bb_ranks` | User ranks/titles | Keep with improvements |
| `bb_auth_access` | Group forum permissions | **Modernize with Laravel policies** |
| `bb_auth_access_snap` | User permission snapshots | **Remove** |
### 5. System Management
| Table | Purpose | Replacement |
|---------------|---------------------------|-----------------------------------|
| `bb_config` | Application configuration | **Replace with Laravel Config** |
| `bb_sessions` | User sessions | **Replace with Laravel Sessions** |
| `bb_cron` | Scheduled task management | **Replace with Laravel Queues** |
| `bb_log` | Action logging | Keep with improvements |
### 6. Messaging System
| Table | Purpose | Replacement |
|--------------------|-------------------------|---------------------------------------|
| `bb_privmsgs` | Private messages | Keep with improvements |
| `bb_privmsgs_text` | Private message content | **Merge into private messages table** |
### 7. Search & Caching
| Table | Purpose | Replacement |
|---------------------|------------------------|--------------------------------|
| `bb_posts_search` | Search index for posts | **Replace with Laravel Scout** |
| `bb_posts_html` | Cached HTML posts | **Replace with Laravel Cache** |
| `bb_search_results` | Search result cache | **Replace with Laravel Scout** |
| `bb_search_rebuild` | Search rebuild status | **Replace with Laravel Scout** |
### 8. Content Management
| Table | Purpose | Replacement |
|---------------|----------------------|---------------------------------|
| `bb_smilies` | Emoticons | Keep with improvements |
| `bb_words` | Word censoring | Keep with improvements |
| `bb_banlist` | User bans | Keep with improvements |
| `bb_disallow` | Disallowed usernames | **Replace with word censoring** |
### 9. Community Features
| Table | Purpose | Replacement |
|-------------------|------------------------------|------------------------|
| `bb_poll_votes` | Poll voting options | Keep with improvements |
| `bb_poll_users` | Poll participation | Keep with improvements |
| `bb_topics_watch` | Topic watching/subscriptions | Keep with improvements |
| `bb_topic_tpl` | Topic templates | **Remove** |
| `bb_thx` | Thanks/voting system | Keep with improvements |
### 10. Buffer/Temporary Tables
| Table | Purpose | Replacement |
|-------------------------|----------------------------|---------------------------------|
| `buf_topic_view` | Topic view counting buffer | **Replace with Laravel Queues** |
| `buf_last_seeder` | Last seeder buffer | **Replace with Laravel Queues** |
| Various snapshot tables | Statistical buffers | **Remove** |
## Major Simplifications for Modern Laravel App
### 1. Attachment System Redesign
**Current**: 7 tables supporting multiple file types with complex quotas
**Modern**: 1-2 tables supporting only torrents and archives
### 2. Remove Buffer/Snapshot Tables
**Current**: 5+ buffer tables for performance optimization
**Modern**: Use Laravel Queues, events, and background jobs
### 3. Modernize Configuration
**Current**: Database-stored configuration in bb_config
**Modern**: Laravel config files and environment variables
### 4. Simplify Authentication/Authorization
**Current**: Complex custom permission system
**Modern**: Laravel Sanctum + Policies + Role-based permissions
### 5. Modern Search
**Current**: Custom search indexing and caching
**Modern**: Laravel Scout with Meilisearch
## Proposed Modern Schema Reduction
**Major Eliminations**:
- Buffer/snapshot tables
- Complex attachment system
- Custom configuration system (replaced by Laravel)
- Custom search system (replaced by Scout)
- Legacy features (topic templates, complex quotas)
## Conclusion
The legacy schema contains significant complexity that was necessary for a custom PHP application but can be greatly simplified using modern Laravel features. The core forum-tracker integration should be preserved while modernizing the implementation approach.