Projects on disk
A project is a plain directory you can read, copy and back up. Nothing in it needs the app to make sense.
projects/
sensor-rail/
project.json name, format, current version, the version table, the chat
draft.json constraints edited but not yet built; not a version
proposal.json, .proposal/ a change built and not yet accepted; not a version
v001/
design.json the design
board.json everything the viewer draws
board.json.before-rejudge the first board.json, kept when a rejudge rewrote it
inspector.html the standalone viewer
sim.json the simulation, when one ran
meshes.json vendor 3D models for the viewer
models/C7593.wrl … the same models for KiCad (.step when asked for)
sensor-rail.kicad_pcb, .kicad_pro, .kicad_sch
sensor-rail-F_Cu.gtl … -Edge_Cuts.gm1, .drl, -NPTH.drl
sensor-rail-In1_Cu.g1, -In2_Cu.g2 inner copper, on a four-layer board
sensor-rail-BOM.csv, -CPL.csv
sensor-rail.dsn
board.svg
source/board.kicad_pcb on a version read from a file: the file as it came
v002/ …
.work/ the router's scratch files; not part of a version
.trash/
old-board-1788254009/ a deleted project, until the trash is emptiedprojects/ sits next to the code in a checkout. Set SOLDERMASK_HOME or
SOLDERMASK_PROJECTS to move it (see Configuration). It is
your data, and it is not in git.
project.json
{
"format": 2,
"name": "Sensor rail",
"description": "",
"tags": [],
"archived": false,
"created": 1788102305.5,
"touched": 1788102889.6,
"current": "v004",
"versions": [
{"id": "v001", "created": 1788102305.5, "summary": "…", "prompt": "…",
"parts": 8, "erc_errors": 1, "gaps": 4, "cost": 3.41,
"parent": "LDO breakout/v002", "app_version": "0.1.0", "label": "", "notes": "",
"passed": true}
],
"variations": [
{"id": "3f9c2a1b", "name": "wide tracks", "macros": {"rules": {"min_track_mm": 1.0}}, "when": 1788102500.1}
],
"chat": [
{"t": 1788102310.2, "you": "a 3.3V LDO breakout", "bot": "Built it around an AMS1117-3.3 …", "version": "v001"},
{"t": 1788102400.7, "you": "what is C1 for?", "bot": "C1 is the input bulk capacitor …", "version": ""}
]
}| Field | What it holds |
|---|---|
format | The on-disk layout's version. See The format number. |
current | The version the app shows and edits. Restoring a version moves only this. |
versions[] | One row per version, oldest first. Rows are never removed. See Rejudging a version for what can change. |
versions[].parent | The version an edit was built from. For a fork's v001, it is <project>/<version>. |
versions[].app_version | Which soldermask built the version |
versions[].passed | The verdict: true, false, or null when the board was not judged |
versions[].label, notes | A name and notes you give the version. Changing them builds nothing. |
variations[] | Saved sets of the rack's knobs: {id, name, macros, when}, in the order they were saved |
chat[] | The conversation, one entry per turn. The last 200 turns are kept. |
imported | On a project read from a bundle: {at, from, app_version} |
auto_name | The project is named from its prompt, and is renamed after its first board |
example | The project is shown under Examples on the projects page |
The chat
Each turn records what was said (you), the answer (bot) and the version it
made. A question makes no version, so its version is "".
| Extra field | Meaning |
|---|---|
kind: "note" | The app started the turn: a rebuild, a route-again, or a file read in |
error: true | The turn failed before it answered. bot holds the reason. |
first | A revised build made two versions. The entry keeps the revision as version and the first as first. |
steps | The build log the page showed: each stage as {phase, at, s}, with s its seconds |
GET /api/projects/<slug> merges the chat with the version table, so the
thread reads back whole. Older projects work too:
- A project from before replies were kept reads back from its versions.
- A note from before the
kindtag is recognised by its wording, such asrebuilt with…,routed again from…orimported….
How writes stay safe
project.json,draft.jsonand a rejudgedboard.jsonare written to a temporary file, which then replaces the old one.- A new version's files are written into a fresh directory, and the version table names it only once they are all there.
- Every change re-reads
project.jsonunder a per-project lock first. The app and the command line cannot lose each other's updates. - A version id counts the versions on disk, under the lock. A directory already standing at the next id is left over from a build that died, and it is deleted first.
- A
project.jsonthat cannot be read is still listed, with the reason. Nothing writes to that project until the file is restored.
The format number
format is the layout's version, separate from the app's version. The app
reads projects up to its own FORMAT, which is 2.
- An older project is migrated the first time it is read. The original is kept beside it as
project.json.pre-format1. - A newer project is refused with a message and left out of the list.
Each migration step is one function in soldermask/projects.py.
| Format | What changed |
|---|---|
| 1 | The original layout: name, created, current, versions |
| 2 | description, tags and archived on the project; app_version, label and notes on each version |
Files in a version
The app sorts a version's files into kinds:
| Kind | Files |
|---|---|
app | design.json, board.json, inspector.html |
gerber | .gtl .gbl .gts .gbs .gto .gbo .gtp .gbp .gm1 .gko .drl .gbr, and inner copper (.g1, .g2 and so on) |
assembly | -BOM.csv, -CPL.csv (and any .xlsx) |
kicad | .kicad_pcb |
router | .dsn, .ses |
preview | board.svg |
other | Everything else, including meshes.json, sim.json, .kicad_pro and .kicad_sch |
gerbers.zip holds the gerber and assembly kinds only.
Rejudging a version
A version's files never change, with one exception: its verdict.
soldermask projects rejudge checks every stored version's copper again with
kicad-cli's DRC. Name a project after it to check only that one.
- Where the answer moved, it writes a new
board.jsonwith the new verdict and arejudgedrecord. - The first
board.jsonis kept asboard.json.before-rejudge, and never overwritten. - The version's row in
project.jsontakes the newpassed.
Add --dry-run to see what would change and write nothing. Naming a version
(label, notes) is the only other change to a row.
draft.json
draft.json is the one file in a project that changes in place. It is why a
drag on the board does not cost a version.
{ "base": "v004", "constraints": { "pinned": { "J1": { "x": 4, "y": 22.5, "rot": 90, "by": "human" } } },
"touched": 1788451932.35 }- You drag a part. About a second later, the new pin is saved here.
- You rebuild. The build writes the constraints into the new version's
design.json. - The draft is deleted.
base is the version the edits amend. A pin dragged onto v004 does not follow
you to v002: v002 keeps the constraints it was built with. A fork copies a
version directory, so it takes the built constraints and none of the draft.
Bundles
export.zip is the project's directory, zipped as it is: project.json,
draft.json if there is one, and every version the table names.
Left out of a bundle: .work/, proposal.json, .proposal/, *.tmp and
project.json.pre-format*.
Importing checks the whole zip before writing anything:
- Every file must be one of those names, or under a
vNNN/the table lists. - Every listed version must have a
design.jsonand aboard.jsonthat parse. currentmust be in the table, and adraft.jsonmust amend a version that is there.- The zip may hold at most 10,000 files and 1 GB unpacked, counted as it unpacks.
- The zip unpacks to
projects/.import-*, then moves into place. A refused zip leaves nothing behind.
Files inside a version whose names start with a dot are skipped, as are
__MACOSX, .DS_Store and Thumbs.db.
A zip you made by hand, with one wrapper folder (and the Mac's __MACOSX beside
it), is accepted and the wrapper removed.
Trash
- Delete moves the project to
projects/.trash/<slug>-<timestamp>. - Restore moves it back under its slug, with a suffix if the slug is taken.
- Empty trash deletes for good. It is the only destructive action in the app.