docs

docs/README.md# Documentation Structure

This directory contains general cross-cutting documentation for the Torrust Tracker Demo project.

For specific documentation:

• Application documentation: ../application/docs/
• Infrastructure documentation: ../infrastructure/docs/

Current Structure

This directory currently contains cross-cutting documentation:

📋 adr/ (Architecture Decision Records)

Important architectural decisions that affect the system structure, behavior, or development process.

📖 See ADR README for complete list, guidelines, and best practices.

📅 plans/ (Ongoing Plans and Roadmaps)

Current Plans:

• Hetzner Migration Plan - Comprehensive plan for migrating from Digital Ocean to Hetzner infrastructure

🎯 issues/ (Implementation Plans)

Issue Implementation Plans:

• Phase 1: MySQL Migration - Detailed implementation plan for database migration from SQLite to MySQL

🏗️ infrastructure/ (Infrastructure Documentation)

Cross-cutting infrastructure documentation - For infrastructure-related documentation that affects the project as a whole or provides reference materials.

Current Infrastructure Documentation:

• SSH Host Key Verification - Explains and resolves SSH host key verification warnings in VM development

User Guides

Deployment, configuration, and testing guides for various scenarios:

• Deployment Guide - Complete deployment guide for local and cloud environments
• Integration Testing Guide -

🔧 refactoring/ (Refactoring Documentation)

Major refactoring initiatives and changes - Documentation of significant codebase changes, architectural improvements, and migration summaries.

Current Refactoring Documentation:

• Integration Test Refactor Summary - Summary of changes made to align integration testing with 12-factor configuration principles

Future Categories

The following directories can be created as needed:

🔬 research/ (Research and Investigations)

Findings, explorations, and technical investigations - For documenting research findings, performance analysis, and technical explorations that span multiple concerns.

📊 benchmarking/ (Performance Testing)

Performance testing and benchmarks - For performance analysis, optimization data, and benchmark results that evaluate the complete system.

🧮 theory/ (Theoretical Documentation)

Mathematical and theoretical concepts - For algorithms, protocols, and theoretical documentation related to BitTorrent and distributed systems.

Contributing to Documentation

When adding new documentation:

1. Check if it belongs in application or infrastructure docs first

   • See ../application/README.md for application documentation guidelines
   • See ../infrastructure/README.md for infrastructure documentation guidelines

2. Use this directory for cross-cutting concerns only

   • Architecture decisions affecting multiple layers
   • Ongoing plans and roadmaps spanning multiple phases
   • Research spanning infrastructure and application
   • Theoretical concepts and protocols
   • Performance analysis of the complete system

3. Create appropriate directories only when you have content to add

4. Use descriptive filenames that clearly indicate the content

5. Follow markdown best practices and maintain consistency

6. Update README files when adding new categories or significant content

7. Cross-reference related documentation when appropriate

Documentation Guidelines

• Cross-cutting vs Specific: Keep layer-specific docs in their respective directories
• Plans: Should document strategic initiatives, migration plans, and multi-phase projects
• Research: Should document findings, methodology, and conclusions
• ADRs: Should follow standard ADR template format and affect multiple layers
• Theory: Should explain concepts clearly with examples when possible
• Benchmarks: Should include methodology, environment, and reproducible results
• Markdown Tables: For tables exceeding line length limits, see .markdownlint.md for proper formatting guidelines