Understanding Project Structure

Clojure projects look simple on disk, but there are a few conventions that are worth learning early. Once you can glance at a repository and predict where a namespace lives, you will read code much faster.

The conventions that matter

• src/ holds production code; test/ holds tests; resources/ holds classpath resources.
• A namespace maps to a file path, roughly like a Java package maps to a directory.
• Hyphens in namespace segments become underscores in file names (my-app.core -> my_app/core.clj).

Java mental model: namespaces are not classes, but the “package-to-path” navigation skill transfers almost directly.

This section gives you the minimum structure you need to follow real projects and avoid “where is this code actually loaded from?” confusion.

In this section

• Map Clojure Namespaces to Files
  Map Clojure namespaces to source files, require aliases, and Java package instincts so namespace loading errors become easy to diagnose.
• Organize Source and Test Directories
  Organize `src`, `test`, and `resources` directories around classpath roots, mirrored test namespaces, and the differences from Maven or Gradle source sets.
• Read Clojure Project Config Files
  Read `deps.edn`, `project.clj`, aliases, and profiles through a Java build-tool lens so you know which file controls dependencies, classpaths, tasks, and local workflow.