Birka's Ubiquitous Language

Table of Contents

• CMS
• Member
• User
• Business Owner
• Developer
• Interface
• Entity Type
• Entity Record
• Product
• Product Section
• Pipeline
• Pipeline Step
• Step Contract
• Pipeline Run
• Theme
• Page
• Blog Post
• Menu

Platform

Platform — it's basically this project's product. This will be a platform suitable for eCommerce and general website building, as well as headless integrations with third-party services. One of its core features is multi-interface support from day one, including REST API, CLI, SSR for public pages, and an MCP server later. The platform includes a CMS to support Business Owners' business operations.

CMS

Frontend SPA GUI for Business Owners to manage Pages, Products, Orders, and other business processes. The CMS is not using SSR and is powered by the platform's REST API.

Member

Admin users and other staff, who can access the CMS and manage the platform through it or through API with elevated rights. Members are not just users with elevated rights; they are a separate entity from site visitor/customer Users.

User

An agent, including a human, LLM agent, script, third-party system, or automated integration that interacts with the platform through an Interface. By default, Users can access any public information. Authenticated Users may also access a broader range of data beyond what is publicly available, though this access remains fixed and defined by the platform.

This excludes scenarios where a Business Owner grants permission elevation, giving Users access to deeper application context.

Business Owner

A Business Owner is an individual or organization that acquires and deploys the Birka project downloading its files, installing them, and building on top of them to serve their own purposes. Business Owners may use the platform directly as end Users and as Members. They also may delegate development and configuration work to developers. In the latter case, Developers may act on behalf of the Business Owner or hold Business Owner status themselves.

Developer

An agent operating on behalf of the Business Owner, unless the Business Owner handles development work themselves. Developers typically install, configure, and launch the platform, and develop on top of it as needed. They are also responsible for creating custom plugins and themes, and building integrations with other services via interfaces provided by the platform.

Interface

A supported way for Users, Members, Business Owners, Developers, or automated agents to interact with platform capabilities. An Interface defines a coherent command or presentation surface for a medium, such as REST API, CLI, CMS, or public site.

Interface code handles input, output, authentication boundaries, and presentation. Entity and application rules stay in core modules.

Entity Type

An Entity Type describes one kind of manageable platform thing, such as Page, Menu, Member, or a registered custom type.

Entity Record

An Entity Record is one persisted instance of an Entity Type, such as one Page or one Menu.

Product

A Product is a sellable offer. Anything the Business Owner sells is represented as a Product, whether it is physical, digital, service-based, access-based, donation-like, or abstract. Product behavior is not determined by fixed product types such as physical, downloadable, or service. It is determined by the Pipeline assigned to the Product.

Pipeline

A Pipeline is a versioned workflow definition that describes how a Product is processed after purchase starts. It defines a business lifecycle promise for a Product, including required fields, choices, conditions, steps, transitions, and outputs.

Pipeline Step

A Pipeline Step is one configured action or decision point inside a Pipeline version. A step can validate input, consume Pipeline fields, produce output, wait for an external signal, expose an action to an Interface, or move the Pipeline Run forward. Pipeline Steps are part of the business workflow.

Pipeline Run

A Pipeline Run is one execution of a Pipeline version for a purchase or order. It stores the current state, selected checkout choices, step outputs, external callbacks, and transition history.

Theme

A Theme is the public-site design chosen by the Business Owner. It controls how visitor-facing web pages look, how their content is arranged, and what kind of experience Users have on the public site.

Page

A Page is a content unit managed by the platform. Semantically, Pages are web pages that are usually accessible to site visitors, while their content can also be retrieved through REST API and CLI Interfaces.

Blog Post

A Blog Post is an authored content unit for article-style publishing. Blog Posts have a publication lifecycle and are meant to be read through the Blog collection or through an individual public Blog Post page.

Menu

A Menu is a named tree of ordered items that point to hardcoded URLs, entity records, or entity-type listing targets. Exactly one Menu is always marked as the routing Menu; the Public Site uses it to resolve public URL paths.