rmb32 / barnark-gui
A web GUI for cloning a template into a project and making its folder, creating what the template offers, and viewing conformance checks
Requires
- php: ^8.5
- ext-ds: ^2.0
- rmb32/barn-paths: ^0.3@dev
- rmb32/barnark: ^0.3.1@dev
- symfony/console: ^8.0
- symfony/process: ^8.0
Requires (Dev)
- infection/infection: ^0.35.4
- phpstan/phpstan: ^2.2
- phpunit/phpunit: ^13.3
- rector/rector: ^2.6
- rmb32/barntree: ^0.1.5@dev
- rmb32/typed-json: ^1.0@dev
- squizlabs/php_codesniffer: ^4.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-15 19:44:36 UTC
README
Early, version 0.x. Not ready for real projects yet; the minor version is the breaking one.
Part of Barn.
A browser UI for Barnark: copy a scaffold into the project, create arks from it, browse each ark's folders, add what its scaffold offers, run conformance checks, and keep scaffolds of your own. (The command line and the code call a scaffold a template.)

The side panel has three headings. Arks lists the project's arks by name. Choose one and its views slide in under a back arrow carrying its name: Tree, Check, History, Scaffold, the ark's own scaffold, and Components. Your scaffolds holds the scaffolds you have copied; Barnark scaffolds holds the ones Barnark ships, read-only, among them Blank project, a single empty folder for a project whose shape is still to be decided. An ark's own scaffold is reached through its ark, never listed.
Every scaffold also shows its Components: the building blocks it is made from, each a folder with a meaning, holding fixed folders, a collection of members or nothing. They are grouped as Placed (in the scaffold's tree) and Available (not placed yet, shown only when there are some). Choose one to see its meaning, its tags and what it holds, with a back arrow to the list.
One of Your scaffolds, or an ark's, takes copies: Copy from… finds a component in any of Your or Barnark's scaffolds (Blank component, an empty folder you name, is always first) and adds a copy with everything it holds, available to place. Nothing in the tree uses it yet, so no folder changes. A component's details offer Copy to… one of Your scaffolds or a new one (never on an ark's component: nothing is copied out of an ark), and an available component in one of your own can be Removed, with what only it holds. Later changes to the original never reach a copy. A copy says where it came from, above its tree on a scaffold's page, on an ark's Scaffold tab and in a component's details: "Copied from Aggregate in Domain Driven Design, revision 3", the original linked while it is there, with "original deleted" once it is gone and, for a Barnark scaffold, "changed in Barnark since" when a later Barnark changed it.
Place on a folder of the scaffold's own tree (or Place a component at its top) puts an available component there, under its own folder name. In an ark its folders are then made, one already made by hand being kept, and a collection arrives empty, ready for members. A component is placed only once. One of Your scaffolds opens on its Tree, where folders are added and their meanings changed as on an ark's Scaffold tab, with nothing made on disk, and its history below. There every folder, a member type's included, offers + (a folder), List (a folder that holds members, with the member type each follows), Meaning and Remove, and the top offers Add a list; Remove asks whether to take the folder out of this scaffold only (it stays available to place again) or to delete its definition too. An ark's tree offers neither List nor Remove: it holds members, so its shape only grows.
To make an ark, choose a Barnark scaffold and Copy to Your scaffolds, under a name such as "My DDD". Then, on your copy, Create ark asks for the ark's name and its folder, and says what it does: "Creates the ark Shop from a copy of My DDD. Later changes to My DDD won't reach it." The ark's own scaffold takes the ark's name. A project can have many arks.
Copy makes a new scaffold of your own from any of yours or an ark's, members included. Delete removes one of Your scaffolds, and only git brings it back; copies made from it, arks included, keep working. An ark and its folder have no Remove: ending an ark's life is not built yet.
In Tree, the tree shows a folder's folders (never its files), and wherever the template has a slot for a folder you name, it offers a button for it — on the directory's own row, and inside the directory once it is open. Click, for example, Create New Context, give the new folder a name, and the template's whole structure for it is scaffolded underneath. The folder panel on the left is dragged to whatever width you like (double-click the divider to put it back).
A member is part of the template, so adding or deleting one makes a new revision, with a reason Barnark writes, such as "Added Context/Billing.". Before a member goes, the delete dialog says so. The History tab lists the template's revisions and shows each as a read-only tree of its fixed folders, member types and members.
The Template tab shows the ark's template's current tree with what each folder means. A folder of
the template's own offers +, to add a folder of yours inside it with a name and a meaning, and
Meaning, to change what it means; Add a folder and Change what /src means do the same for the
ark's folder itself. Each is a new revision. A collection holds only members, so it offers no +, and
nothing inside a member offers anything. In Check, an unexpected folder offers Add to template:
give it a meaning and it becomes part of the template as it is, and the check runs again. If the ark has
file rules (set with barnark rule:set), Check also lists, under File rules, each file in a folder
whose tag has a rule it doesn't match.
A template can tag its folders, as Domain Driven Design tags its layers Application, Domain,
Infrastructure and Transport. A folder's tags show as coloured pills beside its name, in Browse and
in a template's tree; point at one to see what the tag means. Above a template's current tree, a bar
holds each of its tags: choose one to see only the folders with that tag and the folders above them,
every context's Application among them, and choose it again to see the whole tree.
Requirements
Requires Barnark core 0.3 through its installed dependencies; stored barns need no conversion.
- PHP 8.5+
- Node.js (only if you want to develop the frontend)
Installation
Install it alongside Barnark CLI, which then offers barnark gui:
composer require --dev rmb32/barnark-cli rmb32/barnark-gui
Run it
If the barnark CLI is installed in the same project, just run:
barnark gui # http://localhost:8081, opens your browser
barnark gui --port=9000 --no-open
It serves the barn it is started in: the nearest folder at or above the current one that holds a
.barn/ folder, where Barnark keeps its templates and records (.barn/barnark/). It prints the
barn's root and picks the next free port if the default is taken. With no barn there, the page says
so and offers to make one in the folder it was started in; making one adds only the .barn/ folder.
To start the server directly, run this from the Barnark GUI package directory:
BARNARK_GUI_START_DIRECTORY=/path/to/project php -S localhost:8080 -t public
Open http://localhost:8080. BARNARK_GUI_START_DIRECTORY names the folder the search for a barn
starts from, and defaults to the current directory.
To work on the frontend with hot reload:
cd frontend
npm install
npm run dev # proxies /api to localhost:8080, serves on :5173
npm test # Vitest + Testing Library
The served bundle in dist/ is rebuilt with composer build-frontend.
Serving it from your own front controller
BarnarkGuiApp::serve($mountPath, $startDirectory) serves the GUI under a path prefix,
for example /ark, from any PHP router script:
Rmb32\BarnarkGui\BarnarkGuiApp::serve('/ark', '/path/to/project');
The JSON API below then lives under the prefix too (/ark/api/...).
JSON API
| Method | Path | Behaviour |
|---|---|---|
| GET | /api/barn | Return { root, folder }. The root is null if no barn was found. |
| POST | /api/barn | Create .barn/ in the starting folder. Send Content-Type: application/json and an empty JSON object. Returns 409 if the folder is already in a barn. |
| GET | /api/folders | List the project's arks, each with its folder, template and name |
| POST | /api/folders | Clone a template into the project as an ark and make its folder ({ ark, name, baseDir, from, template }, where template names the copy); a refused template name is a 400 |
| GET | /api/folders/{path}/tree?path= | Browse a folder's tree, with the offers (slots that can be filled) at each level and directory, each folder's tags, and the tags its template declares |
| DELETE | /api/folders/{path}/tree?path= | Delete a member or a folder the template doesn't know |
| POST | /api/folders/{path}/members | Add a named member ({ collectionPath, memberType, name }) |
| GET | /api/folders/{path}/check | Run a conformance check against the folder's template |
| POST | /api/folders/{path}/template-folders | Add a folder of the template's own ({ folderPath, meaning }, folderPath inside the ark's folder), then make it unless it is there; returns its rooted path. A change the template can't take is a 409 |
| PUT | /api/folders/{path}/template-folders/meaning | Change what a folder of the template's own means ({ folderPath, meaning }, folderPath "" for the ark's folder); returns { changed } |
| GET | /api/templates | List every template: the arks', your own and the shipped ones, each with its description, folder, shipped and origin (where it was copied from, or null) |
| POST | /api/templates | Copy a template into a new one of your own ({ from, name }) |
| DELETE | /api/templates/{name} | Delete one of your own; a shipped one is a 422 |
| GET | /api/templates/{name}/components | A template's components, placed ones first, each with its shape and, when it was copied in, its origin |
| GET | /api/templates/{name}/shape | A template's tree: nested nodes (fixed, memberType or member), each with its meaning and tags, and the tags the template declares, each with its meaning |
| POST | /api/templates/{name}/tree/{key}/folders | Add a folder ({ name, meaning }) inside the component key of one of Your scaffolds, a member type's or one not placed yet included |
| POST | /api/templates/{name}/tree/{key}/lists | Add a list inside it ({ name, meaning, memberName, memberMeaning }); an ark's template is a 409 |
| PUT | /api/templates/{name}/tree/{key}/meaning | Change what the component means ({ meaning }); returns { changed } |
| DELETE | /api/templates/{name}/tree/{key}?deleteDefinition= | Take the folder out of the tree, keeping its definition unless deleteDefinition=true; returns the keys deleted. The root, a member type, a folder used in several places and an ark's template are a 409 |
| GET | /api/templates/{name}/tags/{tag} | A template's current tree cut down to the folders with the tag and the folders above them; a tag it doesn't declare is a 404 |
| GET | /api/templates/{name}/revisions | List the template's revisions, with reasons, timestamps and the current marker |
| GET | /api/templates/{name}/revisions/current | Read the current template tree, with its tags as shape gives them |
| GET | /api/templates/{name}/revisions/{revisionId} | Read a historical template tree (read-only) |
The JSON API is the bundled frontend's contract with its server, and changes with the frontend in any
release. A {path} or {name} containing / must be URL-encoded as %2F. Folder paths are
canonical: rooted, with a single leading slash (/Widgets). The frontend sends the URL-encoded barn
root as X-Barn-Root on project requests. If that root has changed, the server returns 409 and
asks you to reload.
Related packages
- Barnark — the core library and template catalogue.
- Barnark CLI — the same operations from a terminal.
- Barntree GUI and Barnspek GUI — sibling browser tools.
More docs
Internals · History · Known issues
License
Proprietary. See LICENSE. Copyright (c) Roger Barnfather.