Project Structure

PhotoPrism follows a Go-style monorepo layout with distinct roots for Go packages, the Vue/Vuetify frontend, assets, tooling, and Docker resources. The table below captures the major directories. Use CODEMAP.md in the main repository for an exhaustive, always-up-to-date map.

Path	Purpose & Key Files
/	Top-level Makefile targets (make build-go, make watch-js, make test), multi-arch Docker Compose files, project metadata (README.md, LICENSE, AGENTS.md, CONTRIBUTING.md). Running ./photoprism expects you to be at this root.
/cmd	Entry points for compiled binaries. The CLI/server lives in cmd/photoprism/photoprism.go; any new executable should sit under cmd/<name>.
/internal	Private Go packages (configuration, CLI commands, server, entity models, AI, workers, auth, services). Never import these from external modules. Highlights: internal/commands, internal/server, internal/config, internal/entity, internal/photoprism.
/pkg	Public Go helpers reusable outside the repo (pkg/clean, pkg/fs, pkg/txt, pkg/enum). These packages must not depend on anything in /internal.
/frontend	Vue 3 + Vuetify 3 SPA. src/ holds components, routes, models, CSS; package.json and webpack.config.js define build tooling. Frontend CODEMAP lives in frontend/CODEMAP.md.
/assets	HTML templates (assets/templates/index.gohtml), static JS (assets/static/js/browser-check.js), images, and TensorFlow models.
/docker	Dockerfiles and assets for specialized images (TensorFlow, GPU, ARM). The development stack uses the top-level compose*.yaml files.
/scripts	Bash helpers for CI, release automation, DB initialization. Examples: scripts/*.sh, scripts/dist/*.sh.
/build, /bin	Build artifacts and downloaded tools (golangci-lint, swagger). Should remain untracked or auto-cleaned via Make targets.
/storage	Runtime data when developing locally (SQLite DB, search index, cache, YAML backups). In Docker, this path is mounted from the host.
/test, /setup, /specs	Integration test data, sample configuration files, internal specs used in QA and CI pipelines.

Tips for Contributors

• When adding a new Go package, decide whether it belongs under /internal (private app logic) or /pkg (reusable helper). Only /pkg packages can be imported by external modules.
• Keep CODEMAP.md in sync whenever you move directories or introduce major subsystems.
• Remember to update frontend builds (make build-js) if you touch Vue/JS/CSS files.