rmb32 / barnark
Keeps a project's folders in step with an architecture template: make them from it, and check they still conform.
Requires
- php: ^8.5
- ext-ds: ^2.0
- ext-mbstring: *
- php-ds/php-ds: ^2.0
- rmb32/barn-paths: ^0.3@dev
- rmb32/barntree: ^0.1.5@dev
Requires (Dev)
- deptrac/deptrac: ^4.7
- infection/infection: ^0.35.4
- phpstan/phpstan: ^2.2
- phpunit/phpunit: ^11.0
- rector/rector: ^2.6
- rmb32/barnspek: ^0.1@dev
- rmb32/barnspek-cli: ^0.1@dev
- rmb32/barnspek-gui: ^0.1@dev
- rmb32/barntree-cli: ^0.1.4@dev
- rmb32/filesystem: ^1.0@dev
- rmb32/port-generator: ^0.2@dev
- rmb32/scenario-bridge: ^0.2@dev
- rmb32/scenario-runner: ^0.1.2@dev
- rmb32/typed-input: ^2.0@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-14 21:05:11 UTC
README
Early, version 0.x. Not ready for real projects yet; the minor version is the breaking one.
Part of Barn.
Architecture management for any project. Barnark keeps a catalogue of architecture templates — Domain Driven Design, Feature Based Architecture, Model View Controller, Library, Package App. You clone one into a template of your own, under a name you give it, and Barnark makes a new folder to that template, an ark, and checks that the folder keeps to it. A project can have many arks, each with a name and a template of its own, in the project or anywhere else on your computer. It isn't tied to any single architectural style.
In a barn it is the Ark tab, beside
Barnspek's story map. It works without Barn too: barnark init makes any project a barn.
Its templates are written as Barntree trees. This package is the core library; the command line and browser UI are separate packages.
The easiest way to use it is Barnark GUI, in your browser: create a folder, browse its tree, create what its template offers, and run checks. The command line does the same from a terminal, and is the better fit for scripts, CI and AI agents.

Template maps are presented alphabetically by display name through Barntree, including when reading earlier revisions. List members keep their sequence. Reading a revision leaves the stored revision untouched.
Requirements
- PHP 8.5+
- Composer
Moving to 0.3
TemplateTreeNode takes name, meaning, kind, then optional children, tags and key.
For positional calls written against 0.2.5–0.2.8, remove the leading component key and supply it
as the trailing named argument key: ..., or name every argument as below:
use Rmb32\Barnark\Api\ValueObject\TemplateTreeNode;
use Rmb32\Barnark\Api\ValueObject\TemplateTreeNodeKind;
new TemplateTreeNode(
name: 'Contract',
meaning: 'An interface.',
kind: TemplateTreeNodeKind::Fixed,
key: 'Contracts',
);
Named-argument calls retain their meaning. Stored barns and templates need no conversion.
Installation
composer require --dev rmb32/barnark-cli rmb32/barnark-gui
./vendor/bin/barnark gui # opens the GUI in your browser
The command line brings this library in with it, and the GUI adds its gui
command. Leave the GUI out where only the command line is needed.
docs/installation.md covers a global install and the
files Barnark keeps in your project.
Barnark keeps its records only in a barn: the project's one .barn/ folder, which every Barn tool
shares. Start one with barnark init (or the GUI's offer); Barnark refuses to make a folder where
there is none, and asks before starting one inside another barn.
Barnark is for new projects, and converts no older record.
Quick start
vendor/bin/barnark init
vendor/bin/barnark template:list
vendor/bin/barnark template:copy Library "My Library"
vendor/bin/barnark template:clone "My Library" Billing ./src
vendor/bin/barnark template:offers src/Internal/Feature
vendor/bin/barnark template:new Feature Invoicing src/Internal/Feature
vendor/bin/barnark template:check
vendor/bin/barnark template:copy Billing Invoicing
| Command | Description |
|---|---|
barnark init | Make a barn here if there is none, and say where Barnark keeps its records |
barnark ark:list | List the project's arks: name, folder and template |
barnark template:list | List the arks' templates, your templates and the shipped ones |
barnark template:clone | Make a new ark and its folder from a copy of one of your templates, named after the ark |
barnark template:check | Check an ark against its template, or a given directory against a shipped template |
barnark template:copy | Copy any template into a new template of your own |
barnark template:delete | Delete one of your templates |
barnark template:offers | List what the template lets you create inside a folder |
barnark template:new | Add a folder you name to the template, as a new revision, and make it |
Run barnark <command> --help for every option.
Arks and templates
A shipped template is a read-only catalogue entry. Copying one makes a template of your own: a copy
under a name you give it, which never follows the one it came from. If the shipped template
changes in a later Barnark, yours doesn't. Barnark does remember where each copy came from ("Copied from
Aggregate in Domain Driven Design, revision 3"), and says when that original has been deleted, or, for a
shipped template, has changed in a later Barnark. It records that in .barn/barnark/origins.json, which you
can commit with the rest. Nobody calls their project "Domain Driven Design", so no
shipped template's name can be used for one of yours. Blank project is one shipped template with a
single empty folder, src, for a project whose shape is still to be decided.
A project can have many arks, each made with its folder from one of your own templates, never a
shipped one, by the GUI's Create ark or template:clone. An ark has a name, unique in the project,
that follows a template name's rules, and a template of its own that its folder follows (bound): a
copy named after the ark, or after the ark with a number ("Shop 2") when one of your templates has
that name. Its folder can be anywhere on your computer, and holds a small .barn-ark.json that
points back to the project. Barnark records each ark and its folder in
.barn/barnark/tracked-folders.json, and keeps each of the project's templates, with its revisions, in
.barn/barnark/catalogue/. Commit both, but not the save.lock files written while a template is
saved. The check also says when an ark's link file and the record disagree, and never repairs it. The
project's other templates are unbound, made by copying a shipped template or one of yours. Nothing is
copied out of an ark. An unbound template can make another ark or be
deleted; git keeps it if you need it back. Nothing removes
an ark or its folder: ending an ark's life is not built yet.
Each of the project's templates is kept as revisions, and none is changed in place. Its first revision is the copy, and the GUI's History tab shows each revision as a read-only tree. A folder you name and add (a context, a feature) is part of the template, so adding one makes a new revision, and so does deleting one. Barnark writes each revision's reason, such as "Added Context/Billing.". Nothing changes inside the folders it brings with it: every context has the same shape.
Checking a real project
A template describes a shape, not your code. It names some folders itself (DDD's Kernel, Library's
Api). Others are collections, such as Context or Aggregate, where you add folders of your own
as members, each of the collection's member type. A template says only what folders there are, so
files are checked only by an ark's own file rules (see Tags): what goes in a folder is yours to write.
template:check checks each member against its member type, so your real contexts and aggregates are
checked where they actually are. A folder you make by hand isn't added to the template, but one made
in a collection can only be a member of it, so it is checked as one. A folder made by hand anywhere
else is reported as unexpected. A folder in the template that has been deleted by hand is reported as
missing.
The barn's .barn/ folder is never part of an ark.
Creating by the template
template:new adds a member you name to a collection, and its folder arrives with the folders its
member type holds: a Context comes with its Domain, Application, Infrastructure and
PublicApi. Barnark never creates a file in your folders, except a .gitkeep so that git keeps a
folder created empty.
Tags
A template can tag its folders, to say what part each plays. Domain Driven Design tags its layers:
Application, Domain and Infrastructure in the Kernel and in every Context, and Transport. Package
App tags each Context's Application and Infrastructure. A tag has a meaning, and a folder carries
the tags of its kind of folder, so every Context you add brings its layers' tags. A folder the template
has no place for carries none. Picking out a tag shows the template's folders that carry it and the
folders above them, such as every context's Application/ together.
You can tag the folders of one of your own templates too (tagFolderInTemplate()), by the key of the
folder's component, and untag them. When a component is used in several places, tagging or untagging it
reaches every occurrence. A tag belongs to that component's folders alone, never to the folders inside
them. An ark keeps the tags its template had when it was made, so tag the template first.
File rules
Tags are what an ark's file rules go by. A rule says that each file directly in a folder carrying a tag
must have a name that matches one of some patterns (*.php, *.ts, [ab]?.md; capitals count), or that
the folder holds no file at all. setRule() makes one for an ark, and template:check then reports each
file that doesn't match, and each rule for a tag its template doesn't declare. A file whose name starts with
a dot is never seen, so a folder holding only a .gitkeep is empty. The rules are in the ark's own file,
.barn/barnark/rules/<ark>.json, which Git keeps the history of; copying a template copies no rules. These
are findings, never a block, and only for an ark.
From PHP
Each factory in Rmb32\Barnark\Api\Factory gives you one part of Barnark.
use Rmb32\Barnark\Api\Factory\ArchitectureFactory;
use Rmb32\Barnark\Api\Factory\ProjectFactory;
use Rmb32\Barnark\Api\Factory\TemplateProfileRegistryFactory;
$names = new TemplateProfileRegistryFactory()->create()->names(); // the shipped templates
To see what a template looks like, read its tree: each Node is a folder every
scaffold has, and each MemberType is a kind of folder you create and name,
each with the meaning the template gives it.
$template = new TemplateProfileRegistryFactory()->create()->get('Domain Driven Design');
$template->description(); // what it is and what it suits
$template->root()->nodes[0]->name; // "Kernel", a folder every scaffold has
$template->root()->nodes[0]->memberTypes; // MemberType[]: what you may create in it
$template->tags(); // Tag[]: Application, Domain, Infrastructure, Transport
$template->root()->nodes[0]->nodes[0]->tags; // ["Application"]: the tags a folder carries
new ArchitectureFactory()->create()->planScaffold('Library'); // ["Api", "Api/Contract", ...]
$project = new ProjectFactory()->open('/path/to/project'); // a barn started with barnark init
$project->copyTemplate('Library', 'My Library'); // a template of your own, copied from a shipped one
$project->createFolder('src', '', 'My Library', 'Billing'); // the ark Billing: a copy named Billing, and src/ made to it
$project->check('/path/to/project/src', 'Billing', $project->slotsFor('src')); // slotsFor: each member's path and member type
$project->pickOutByTag('Domain Driven Design', 'Application'); // only the folders tagged Application, and those above them
$project->components('Library'); // Component[]: its building blocks, placed or only available
$project->copyComponent('Domain Driven Design', 'Domain', 'My Library', 'Domain'); // a copy, available to place, with what it holds
$project->removeComponent('My Library', 'Domain'); // takes the copy out again, with what only it holds
$project->placeComponent('Shop', 'Internal', 'Transport'); // places an available one; in an ark its folders are made
$project->addFolderToTemplate('My Library', 'Api/Http', 'HTTP.'); // a folder of its own in one of your templates
$project->addListToComponent('My Library', 'Project', 'Contexts', 'Each context.', 'Context', 'A context.'); // a list of its own, by key
$project->addFolderToComponent('My Library', 'Context', 'Domain', 'What it knows.'); // inside the list's member type, by key
$project->removeFolderFromTemplate('My Library', 'Contracts', false); // out of the tree, still available; true deletes it too
$project->originOf('My Library')?->describe(); // "Copied from Library (Barnark 0.2.6)"; a Component carries its own `origin`
ProjectFactory::create($root) manages a project's arks and its templates
(listTemplates, copyTemplate, deleteTemplate, originOf) and their components (components, copyComponent,
removeComponent, placeComponent), their folders (addFolderToTemplate, changeFolderMeaningInTemplate; in one of your own, by a component's key,
addFolderToComponent, addListToComponent, changeComponentMeaning, removeFolderFromTemplate), and
CheckFactory checks a directory against a shipped template, returning a Violation
for each folder that is missing or not part of it.
Related packages
- Barnark CLI — the
barnarkcommand. - Barnark GUI — clone a template into the project, browse its folder, create what its template offers, run checks and keep templates of your own, in a browser.
- Barntree — the trees the templates are written as.
More docs
Installation · Internals · History · Known issues
License
Proprietary. See LICENSE. Copyright (c) Roger Barnfather.