Note: I have now updated this with the latest roadmaps for 10.15 release. A further article will follow on 11 October explaining more about these.

When you upgrade to macOS 10.15 Catalina, your boot volume will effectively be split into two. Assuming it’s the standard internal storage, your existing boot volume will be renamed to Macintosh HD – Data, and a new read-only system volume created and given the name Macintosh HD. However, when your Mac starts up in Catalina, you won’t see the Data volume, as it’s hidden inside the System volume, in what Apple refers to as a Volume Group.

Although new to macOS, this scheme is already in use in iOS, and specifies the read-only system volume as having the role APFS_VOL_ROLE_SYSTEM, and the writeable user volume has the role APFS_VOL_ROLE_DATA. In that, the volume with the System role is normally mounted at the root /, and that containing both user and mutable system data is then mounted in /System/Volumes and accessed from there using several firmlinks.

In this scheme, inode numbers are allocated relative to the root, so the files and directories of both volumes share the same volume inode and number space. Thus you can’t distinguish where an item is located by checking its volume inode. Furthermore, absolute URL paths are given from the root directory /, so they too don’t reveal which of the volumes in the volume group an item is stored on.

Inode numbers do make it easy to identify firmlinks: just like hard links, the two directories forming the firmlink have identical inode numbers, although as they are directories and APFS doesn’t support directory hard links, they can only be firmlinks.

A bootable Catalina APFS container normally contains at least five APFS volumes:

• the read-only system volume, by default on the internal disk named Macintosh HD, which forms the root of the boot file system,
• the writable data volume, by default on the internal disk named Macintosh HD – Data, which is normally hidden from view at /System/Volumes and accessed via firmlinks,
• Preboot, a small volume of around 40-50 MB,
• Recovery, the Recovery Volume, of around 500 MB,
• VM, containing virtual memory caches, which is upwards of 20 KB depending on use.

Firmlinks are similar in some respects to traditional symbolic links, but are only made between folders, work in both directions, and with a little added magic effectively merge the contents of two linked folders. For example, the /Users directory on the read-only system volume contains some directories in /Shared. As /Users is a firmlink, the directories there are merged with those in the /Users/Shared directory on the writable (Data) volume.

A similar trick applies to the /Applications directory: user applications are installed in the Applications directory on the writable volume; SIP-protected Apple apps are installed in /System/Applications, which resides on the read-only system volume. When you browse the top-level Applications folder in the Finder, you’ll see the combination of both sets of apps, with user apps linked in using a firmlink between the two volumes. Further details about volume groups and the file system magic in Catalina is in this Carbon Copy Cloner KB article.

Layout of standard folders and files on the System volume is shown in this roadmap:

 

available here as a PDF: CatalinaSysR

If you want the previous version, for late beta releases, here it is in PDF: CatalinaSys

Layout of standard folders and files on the Data volume is shown in this roadmap:

 

available here as a PDF: CatalinaDataR

If you want the previous version, for late beta releases, here it is in PDF: CatalineData

The current list of firmlinks taken from /usr/share/firmlinks is:
/Applications <-> Applications
/Library <-> Library
/System/Library/Caches <-> System/Library/Caches
/System/Library/Assets <-> System/Library/Assets
/System/Library/PreinstalledAssets <-> System/Library/PreinstalledAssets
/System/Library/AssetsV2 <-> System/Library/AssetsV2
/System/Library/PreinstalledAssetsV2 <-> System/Library/PreinstalledAssetsV2
/System/Library/CoreServices/CoreTypes.bundle/Contents/Library <-> System/Library/CoreServices/CoreTypes.bundle/Contents/Library
/System/Library/Speech <-> System/Library/Speech
/Users <-> Users
/Volumes <-> Volumes
/cores <-> cores
/opt <-> opt
/private <-> private
/usr/local <-> usr/local
/usr/libexec/cups <-> usr/libexec/cups
/usr/share/snmp <-> usr/share/snmp
in each case shown as the system volume path and the Data volume path which are firmlinked. These haven’t changed since late betas.

One valuable trick for always using the right path in Terminal is to locate the folder or file in a Finder window, and drag and drop that into the command line. macOS then magically performs any path conversions for you. You may also find my utility Precize useful, as it gives paths, inode numbers, and a great deal more.

For details of the roles and purposes of these folders, and those within the Home folder, please refer back to the previous article detailing the volume layout of macOS 10.14 Mojave.

Details given here are based on exploration of the file system of Catalina 10.15 first full release.

Amended 1535 UTC 10 October 2019 for the release version.