Search by

rmb32 / barnark

rogerbarnfather

Keeps a project's folders in step with an architecture template: make them from it, and check they still conform.

v0.3.1 2026-11-14 20:41 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.

The Barnark GUI: Hotel’s Tree view at /src, with FrontDesk, Property and Reservation contexts, a Booking aggregate, layer tags and buttons for new members.

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
CommandDescription
barnark initMake a barn here if there is none, and say where Barnark keeps its records
barnark ark:listList the project's arks: name, folder and template
barnark template:listList the arks' templates, your templates and the shipped ones
barnark template:cloneMake a new ark and its folder from a copy of one of your templates, named after the ark
barnark template:checkCheck an ark against its template, or a given directory against a shipped template
barnark template:copyCopy any template into a new template of your own
barnark template:deleteDelete one of your templates
barnark template:offersList what the template lets you create inside a folder
barnark template:newAdd 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 barnark command.
  • 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.