# The Zotonic workspace

Source: https://zotonic.com/docs/2176/the-zotonic-workspace

URI: https://zotonic.com/id/2176

Language: en

The checkout is an Erlang umbrella project: one build contains many applications.

- `apps/` contains Zotonic's core applications and bundled modules.
- `apps_user/` contains your sites and additional modules.
- `apps_user/<project>/apps/` can contain applications in a nested project; this path is included in the current build configuration.
- `_build/` contains build output and dependencies. Do not treat it as the authoritative source directory.
- `doc/` contains versioned documentation and reference sources.
- `bin/zotonic` is the command-line entry point.

A site or external module can be its own Git repository inside `apps_user`. Before changing files, check which repository owns them. Add dependencies in the appropriate `rebar.config`, then build from the umbrella root.

What belongs in src and priv
----------------------------

Use `src` for compiled Erlang code and `priv` for application resources.

Put request handling in `controllers`, model APIs in `models`, template transformations in `filters`, rendered components in `scomps`, and supporting business logic in `support`. Directory names help readers; the Erlang module name and exported callbacks still determine behavior.

Under `priv`, put routes in `dispatch`, templates in `templates`, browser-ready files in `lib`, and their editable build sources in `lib-src`. Translation catalogs belong in `translations`.

Do not put uploaded files, caches, or local secrets in a deployable assets directory. Use the site's configured storage and configuration mechanisms. Do not edit generated CSS when its source and build command are available.

Runtime data and uploaded files
-------------------------------

Keep runtime data separate from the application's source and static assets.

Site media, generated previews, backups, logs, and caches can live outside the checkout. Their locations depend on the running installation's configuration. Use Zotonic's storage and path APIs rather than assuming a relative directory beside a template.

For media, work through <a href="/id/1284" class="doc-reference doc-reference-model"><code>model#media</code></a> and related storage facilities so metadata, preview generation, access checks, and storage backends remain coordinated. Never replace a file behind the model's back as a normal upload workflow.

When deploying, preserve the site's durable files as well as its database. Rebuilding `_build` is not a backup or migration strategy for uploaded content.

License: 

Attribution: 

Related resources: https://zotonic.com/api/agent/related/2176?language=en


## API access

- [API help](<https://zotonic.com/api-help>)
- [OpenAPI specification](<https://zotonic.com/openapi.json>)
- [This resource as JSON](<https://zotonic.com/api/agent/resource/2176?language=en>)
