index.md

semantic-links

skill-links related-artifacts write-markdown-docs docs/AGENTS.md docs/analysis/AGENTS.md docs/research/AGENTS.md docs/architecture/README.md docs/adrs/20260821172000_establish_ai_agent_context_capability_and_portability_governance.md docs/benchmarking.md docs/application-jobs.md docs/containers.md docs/packages.md docs/profiling.md docs/release_process.md docs/testing/README.md docs/adrs/README.md docs/adrs/index.md docs/issues/README.md docs/copilot-pr-reviews/README.md docs/pr-review-feedback/README.md docs/refactor-plans/closed/README.md docs/refactor-plans/drafts/README.md docs/refactor-plans/open/README.md

Torrust Tracker — Documentation Index

This is the entry point for all project documentation. For API documentation generated from source code, see the crate docs on docs.rs.

Guides

Operational and development guides for working with the tracker.

Document	Description
application-jobs.md	Current background-job ownership, lifecycle, and shutdown behavior
benchmarking.md	How to run and interpret the torrent-repository benchmarks
containers.md	Building and running the tracker with Docker / Podman
git-hooks.md	Hook behavior and SSH idle-timeout troubleshooting
packages.md	Workspace package catalog, architecture layers, and dependency rules
Configuration v2-to-v3 migration guide	Upgrade tracker configuration files to active schema v3
profiling.md	CPU and memory profiling with Valgrind / kcachegrind
release_process.md	Branch strategy, versioning, and the staging → main release pipeline
testing.md	Test-layer selection strategy, evidence boundaries, and validation owners
testing/README.md	Testing guidance and a catalog of durable test-design refactoring patterns
adrs/20260821172000_establish_ai_agent_context_capability_and_portability_governance.md	Governance for portable AI-agent workflows and retained context

Runtime Architecture

Guides describing the running application's composition and behavior. They complement ADRs, which record accepted architectural decisions.

Document	Description
architecture/README.md	Runtime architecture index: tracker instances, shared services, and event topology.

AI Agents

Repository-owned documentation of the current workflows between custom AI-agent profiles. It does not replace profile definitions or technically enforce agent transitions.

Document	Description
agents/README.md	AI-agent documentation index and workflow references.
agents/orchestration.md	Agent handoffs, prerequisites, feedback loops, artifacts, and enforcement boundary.

Architecture Decisions (ADRs)

Records of significant architectural decisions, including context and consequences.

Document	Description
adrs/README.md	Root ADR guidance, including placement by decision scope
adrs/index.md	Quick-reference table of repository-level ADRs

Analysis Documents

In-depth studies of concrete features, components, or aspects of the application, typically produced before defining a refactoring plan, introducing a new feature, or making architectural decisions.

Location	Description
analysis/AGENTS.md	Overview of the analysis folder and its conventions
analysis/20260716-shutdown-process/	Analysis of the tracker shutdown process
analysis/20260909-cli-config-path-test-isolation/	Analysis of configuration injection and test isolation

Research Documents

Investigations of external topics, technologies, or patterns relevant to the project. Research looks outward — at how other projects solve similar problems.

Location	Description
research/AGENTS.md	Overview of the research folder and its conventions
research/20260716-console-shutdown-patterns/	How console apps handle SIGINT, SIGTERM, and graceful shutdown

Issue Specifications

Structured specification documents linked to GitHub issues. Used for planning and tracking implementation work before and during development.

Location	Description
issues/README.md	Overview, folder structure, and workflow skill references
issues/drafts/	Specs not yet linked to a GitHub issue
issues/open/	Active specs for open GitHub issues
issues/closed/	Recently closed specs kept temporarily for reference

Refactor Plans

Specification documents for larger refactoring efforts, following the same lifecycle as issue specs (drafts → open → closed).

Location	Description
refactor-plans/drafts/	Draft refactor plans not yet tied to a GitHub issue
refactor-plans/open/	Active refactor plan specs
refactor-plans/closed/	Completed refactor plans kept for reference

Copilot PR Reviews

Records of Copilot pull request suggestion reviews.

Document	Description
copilot-pr-reviews/README.md	Overview of the Copilot PR review archive

Pull Request Review Feedback

Records of review summaries, their independently tracked findings, and consolidated responses.

Document	Description
pr-review-feedback/README.md	Overview of the PR review feedback archive

Skills and Conventions

Internal documentation on project-specific conventions used by both humans and AI agents.

Document	Description
skills/semantic-skill-link-convention.md	Frontmatter schema, skill-link marker catalog, and machine-readable metadata conventions

Templates

Canonical document templates. Copy the appropriate template when creating a new artifact of that type.

Template	Description
templates/ADR.md	Template for Architectural Decision Records
templates/AGENT-REVIEW-REPORTS.md	Template for chronological issue-local independent-review reports
templates/EPIC.md	Template for EPIC issue specifications
templates/IMPLEMENTATION-RETROSPECTIVE.md	Template for issue-local implementation retrospectives
templates/ISSUE.md	Template for task / bug / feature issue specifications
templates/REFACTOR-PLAN.md	Template for refactor plan specifications
templates/SECURITY-ANALYSIS.md	Template for public scanner-finding and vulnerability analysis
templates/SECURITY-REPORT.md	Template for handled coordinated-disclosure records
templates/COPILOT-SUGGESTIONS-TEMPLATE.md	Template for recording Copilot PR review suggestions
templates/PR-REVIEW-FEEDBACK-TEMPLATE.md	Template for tracking PR review findings and responses

Media

Images, diagrams, flamegraphs, benchmark reports, and sample torrent files used in documentation.

Location	Description
media/	Top-level media assets (flamegraphs, benchmark screenshots, sample torrents)
media/demo/	Screenshots and assets used in demo documentation
media/packages/	Package architecture diagrams

Licenses

Full license texts referenced by the project.

Location	Description
licenses/	AGPL-3.0 and MIT-0 license files