Instruction 01-arr-stack-data-architecture-and-the: Reading

The central design rule is that applications participating in an import should describe shared files with one consistent namespace. In the /data model, download clients write beneath /data/torrents or /data/usenet, while Sonarr and Radarr organize completed media beneath /data/media. A typical layout is /data/torrents/tv, /data/torrents/movies, /data/usenet/complete/tv, /data/usenet/complete/movies, /data/media/tv, and /data/media/movies. The application configuration directories are not placed inside this tree; each service instead receives a separate configuration location because databases and settings have different backup, access, and lifecycle requirements from large media files.

Consistency is more important than inventing a unique path for every container. If a download client reports /data/torrents/tv/Episode.mkv, Sonarr should be able to inspect that exact path. Mounting the host download directory as /downloads in one container and as /data/torrents in another creates a translation problem. It also encourages separate container mount points that can prevent efficient imports. A unified /data bind mount gives the participating applications a shared view. The applications may receive read-only or narrower access where their role permits it, but an importer must be able to read the completed download and write into its library destination.

Hardlinks are especially useful for torrents. A torrent client must retain its original path while seeding, but the media server expects a clean library path and filename. A hardlink allows both names to reference one inode, so deleting one name does not remove the data while another link remains. Hardlinks require source and destination to be on the same filesystem and cannot be created across filesystem boundaries. They also require suitable permissions on the source and destination directories. The inode number and device number reported by stat can prove whether two paths are hardlinks. A link count of two or greater shows that the inode has multiple names.

Atomic moves provide another benefit of a unified filesystem. When an application renames a completed file within one filesystem, the operation can update directory metadata rather than copying the file and then deleting the original. If source and destination are on different filesystems, the workflow becomes a copy followed by deletion and is no longer an atomic rename. Usenet workflows commonly move completed files because continued seeding is not required, while torrent workflows commonly preserve the download and create a hardlink into the library.

Path design does not replace identity and permission design. Sonarr, Radarr, and download clients should use compatible user and group identities, and shared directories should be group-writable where collaboration is required. Broad access is not a substitute for understanding ownership. Categories must also agree: a Sonarr category such as tv should correspond to the download client's /data/torrents/tv or /data/usenet/complete/tv location, while Radarr should use movies. Remote path mappings should be reserved for genuinely remote or legacy path differences; they should not be used to conceal a poor local container mount design. Before deployment, document the host path, container path, writer, reader, ownership expectation, backup policy, and deletion authority for every directory.