# Projects

A project is one industrial application: its tags, screens, transactions, queries, and users, in one folder under projects/. The project.toml manifest declares identity, branding, scope, and auth.

## One folder per application.

```
projects/press-line/
├── project.toml            # manifest — this page
├── users.toml              # project-local users (argon2id hashes)
├── tags/                   # [[tags]] files, subdirs allowed
│   ├── hydraulics.toml
│   └── recipes.toml
├── screens/                # one folder per screen
│   ├── overview/
│   │   ├── index.html
│   │   ├── screen.js
│   │   └── style.css
│   └── alarms/
│       └── index.html
├── transactions/           # SQL logging groups
│   └── cycle-log.toml
└── queries/                # named SQL queries
    └── active-recipes.toml
```

`thermite project init <slug>` creates the folder and a fresh manifest. Organize `tags/` however you like — files load recursively.

## A real project.toml.

A representative manifest, patterned on the reference press project. Retain the `id` generated by init and set `slug` to the folder name. These are the required fields; the remaining fields are optional.

```toml
# projects/press-line/project.toml
[project]
id = "01979000-0000-7000-8000-000000e14400"
slug = "press-line"
name = "600t Press"
description = "Hydraulic forming press — monitoring, recipes, setpoint control."
enabled = true
home_screen = "overview"

[project.branding]
app_title = "Press Line"
primary_color = "#f97316"

[project.scope]
devices = ["press-plc"]

[project.auth]
inherit = false
sources = ["local"]

[project.auth.source.local]
type = "embedded"
credentials_file = "users.toml"

[[project.auth.bindings]]
source = "local"
username = "operator"
roles = ["operator"]

[project.auth.roles.operator]
can_write_tags = true
```

Enable gateway \[auth\].enabled to enforce project access. Auth sources, bindings, and role flags are covered in depth on [Users, roles & security](https://thermitescada.com/docs/security.md).

## Identity.

| Field | Default | Description |
| --- | --- | --- |
| `id` | `generated` | Immutable project UUID — keys sessions, tag scopes, and the published store. thermite project init generates it; never reuse one. |
| `slug` | `required` | URL-safe name; must equal the folder name. Mounts the project at `/p/<slug>/`. |
| `name` | `—` | Display name. |
| `description` | `—` | Shown in project listings. |
| `version` | `—` | Free-form version string. |
| `enabled` | `true` | Disable to keep the project on disk but unmounted. |
| `home_screen` | `—` | Screen served at the project root (and after login). |
| `slug_aliases` | `[]` | Names reserved during uniqueness checks. Routes use the current slug; update application links after a rename. |

## Per-project look.

| Field | Default | Description |
| --- | --- | --- |
| `app_title` | `—` | Title on the project sign-in page. Set each screen's browser title in its HTML. |
| `primary_color` | `—` | Accent color, e.g. "#f97316". |
| `logo / favicon` | `—` | Asset names relative to the project's branding/ directory, e.g. logo.svg. |

## Which site resources it may touch.

| Field | Default | Description |
| --- | --- | --- |
| `devices` | `all` | Allow-list of site devices this project's tags may bind to. Tags referencing out-of-scope devices are skipped, with a warning at publish. |
| `databases` | `all` | Allow-list of site databases for transactions and queries. |

## Where it's served.

| Field | Default | Description |
| --- | --- | --- |
| `path_mode` | `true` | Serve under `/p/<slug>/` on the gateway port. |
| `port` | `—` | Add a dedicated production listener. Set path_mode = false to serve exclusively on that port. Drafts cannot declare a port. |
| `bind_address` | `gateway's` | Bind address for a dedicated listener. |

## What projects share, and what they don't.

### Shared (site-level)

- Device connections — one PLC session serves every project scoped to it.
- Database connections.
- Scan groups and the gateway port.

### Per-project

- Tag namespace — paths are scoped to the project.
- With authentication enabled, users, roles, and sessions are scoped per project and draft.
- Screens, branding, transactions, queries, and publish lifecycle.

## Snapshot project source into a named draft.

`thermite project draft <slug> <name>` snapshots the *current* `projects/<slug>/` source into an independent slot at `/draft/<slug>/<name>/`. Re-run the command to replace that slot. Drafts have separate tag values and session scopes but share gateway device connections; draft writes can affect connected equipment. Change production screen files with `thermite project publish` — see [Publishing & the CLI](https://thermitescada.com/docs/publishing.md).
