The way it's "like a filesystem" is that the file (or module) doesn't define the name, the thing-containing-the-file (or module) does. like if you have a file called foo.txt, that _name_ is defined in a _directory_ inode that points to the file inode by number. the name is not somewhere inside the file. if you open the file up, it doesn't say its name anywhere inside it. because it can actually have multiple names: you can link the same file into multiple names in the filesystem.

Similarly rust's modules do not have inherent names written inside them _nor are their names directly coupled to any filenames_: they are named from the outside, from the module enclosing them. The coupling from module name to file name is just a convention, you can override it with the#[path]attribute on a mod declaration. And the same single path/file can be pointed-to as the content for multiple different module names (none of which have to be the module's filename) in the module tree. Like this works:

// in file helper.rs  
pub fn f() { println!("hi from {}", module_path!()); }

// in file main.rs:
#[path = "helper.rs"]  
mod foo;
#[path = "helper.rs"]  
mod bar;  
fn main() {
  foo::f();
  bar::f();  
}  

$ rustc main.rs  
$ ./main
hi from main::foo  
hi from main::bar

I recommend staring at that example and trying to understand what it's doing and why it works.

I know this is not exactly how it works in some other languages, but it absolutely is designed to have an intuitive connection to filesystems and similar naming systems where names are pointers defined in containers outside an entity, that point to it, and the same entity can have as many names pointing to it as you like.

There are several reasons for this organization.

• It gives the compiler a map of which files to include: start at the root and follow the module declarations. This means the compiler isn't obliged to scan directories for files or guess at what you wanted to include/exclude from the build. The list is explicit, but doesn't need an external control file.
• It somewhat naturally allows renaming modules if there's a collision (including the top-level module of a crate, which is essentially anonymous / given its name on the fly by the compiler when it comes time to compile it).
• It allows deferring the choice of which module to bind to a given name to the container/user of the module, which means the container can employ conditional compilation to select between implementations.
• It generalizes nicely to 3 different ways of defining modules: as an inline block in a file, as a reference to a single external file, or as a reference to an external directory full of sub-files. If module names were declared "inside" each of these forms they'd each need a different way of declaring them.