Foundational
Companion to:
This document defines the runtime architecture of the Pancakes ecosystem.
It explains how applications execute within a Pancakes node while sharing common infrastructure provided by the node and by Pitchfork.
The architecture intentionally separates responsibilities between applications, shared runtime services, accounting infrastructure, and node governance.
This document defines:
It does not define:
Those subjects are defined in companion documents.
Pancakes is not a single application.
It is a runtime environment supporting many independent applications operating over a common foundation.
Applications should not reimplement infrastructure that already exists within the node.
Instead they should consume shared services that provide:
This separation allows applications to evolve independently while remaining compatible with the broader ecosystem.
At runtime, applications communicate with a Pancakes node through a common runtime interface.
The node provides shared infrastructure while Pitchfork provides symbolic and accounting services.
The overall architecture is illustrated below.
Client
│
▼
Node Interface
│
┌──────────┴──────────┐
▼ ▼
Node Capabilities Reference Services
└──────────┬──────────┘
▼
Identity & Permissions
▼
Pitchfork
▼
Settlement / Contracts
Recipes / Projections
▼
Client Presentation
Each layer has a distinct responsibility.
Applications remain independent while sharing the layers beneath them.
Applications provide experiences for people.
Examples include:
Clients own:
Clients should avoid owning shared infrastructure.
The runtime layer provides reusable services shared by all clients.
Examples include:
This layer provides operational consistency throughout the ecosystem.
Pitchfork provides the symbolic and accounting substrate shared by clients.
Responsibilities include:
Applications consume symbolic information without redefining accounting.
Every runtime operates inside a Pancakes node.
Nodes define:
The runtime architecture depends upon nodes but does not define them.
The runtime architecture follows several guiding principles.
Applications operate within the context of a node.
Applications do not communicate directly with arbitrary infrastructure.
Instead they interact through the runtime services provided by their current node.
This allows the same application to function in:
Reusable services belong to the node rather than individual applications.
Examples include:
Applications consume these services instead of duplicating them.
Applications remain independent from one another.
A wellness application should not depend directly upon an RPG.
A service exchange should not depend directly upon a menstrual calendar.
Instead each application communicates through shared runtime infrastructure.
This greatly reduces coupling between projects.
New applications should be created by composing existing runtime services.
Developers should rarely need to modify existing applications in order to add new ones.
The architecture therefore encourages:
Applications should not assume they may observe or expose information simply because it exists.
Information first passes through:
Only then may applications request projections appropriate to the current user and context.
This principle reduces unnecessary disclosure while allowing multiple applications to interpret the same underlying activity differently.
Runtime services should assume that local operation is normal.
Networking, hosted deployments, and federation expand local capability.
They do not replace it.
Applications should continue providing meaningful functionality whenever local operation remains possible.
Applications should depend upon stable runtime concepts rather than deployment details.
For example, an application should depend upon:
It should not depend upon:
Stable runtime abstractions allow the ecosystem to evolve without requiring every application to evolve simultaneously.
The runtime architecture intentionally separates responsibilities.
Applications provide experiences.
Nodes provide operational infrastructure.
Pitchfork provides symbolic and accounting infrastructure.
Communities provide governance.
This separation allows each layer to evolve independently while preserving a coherent ecosystem.
Every architectural concept should therefore have one canonical home.
Applications consume shared infrastructure.
Nodes host it.
Pitchfork interprets it.
Communities govern it.
The Node Interface provides the stable runtime boundary between applications and the infrastructure hosted by a Pancakes node.
Applications interact with the node through this interface rather than communicating directly with internal services.
This separation allows:
The Node Interface is therefore the primary abstraction that applications target during execution.
The Node Interface is responsible for:
It intentionally avoids embedding application-specific behavior.
Applications should depend upon runtime behavior rather than implementation details.
For example, an application should request:
It should not depend upon:
The runtime contract should remain stable even as implementation evolves.
Every Pancakes node provides a collection of reusable runtime services.
These services form the operational foundation upon which applications execute.
Applications should consume these services whenever practical rather than creating parallel infrastructure.
The identity service establishes who is participating within the current node.
It manages identities for:
Identity provides continuity across applications while remaining governed by the local node.
Permission services determine what actions an identity may perform.
Permissions govern access to:
Permission policies belong to the node rather than to individual applications.
This allows communities to apply consistent governance across multiple clients.
Capabilities represent reusable operational services provided by the node.
Examples include:
Applications discover and consume capabilities dynamically rather than assuming that every deployment provides identical functionality.
Capabilities therefore make the ecosystem modular while preserving runtime consistency.
Reference services provide shared knowledge that may be used by many applications.
Examples include:
Reference services provide common understanding without prescribing application behavior.
Applications interpret this information according to their own domain.
Storage services preserve information on behalf of both applications and shared runtime infrastructure.
Storage includes:
Applications should avoid assuming particular storage technologies.
The runtime provides persistence as a shared service.
Synchronization services coordinate information between:
Synchronization is a runtime responsibility rather than an application responsibility.
Applications should describe desired state while allowing the runtime to manage transport and reconciliation.
Notification services provide communication between runtime components and applications.
Examples include:
Notification delivery should respect permissions and local governance.
Administrative services expose operational facilities required by the node.
Examples include:
Applications should rarely require direct access to administrative functions.
Pitchfork provides the shared symbolic and accounting infrastructure used by all participating applications.
Rather than embedding independent accounting systems within each client, applications share a common symbolic substrate.
This allows different applications to interpret the same activity without duplicating state.
Applications describe meaningful events occurring within their domain.
Examples include:
Applications describe events.
Pitchfork records them.
Settlement transforms recorded events into durable symbolic state.
Settlement is responsible for maintaining consistency across:
Applications consume settled information rather than attempting to maintain their own independent accounting.
Contracts provide structured agreements between participants.
Applications create and fulfill contracts through Pitchfork.
Pitchfork maintains:
Applications remain responsible for presenting these relationships to users.
Recipes describe repeatable symbolic transformations.
Examples include:
Applications invoke recipes.
Pitchfork evaluates symbolic consequences.
Pitchfork maintains shared symbolic state describing the current consequences of settled activity.
Examples include:
Applications interpret symbolic state without redefining it.
One of the primary responsibilities of the runtime architecture is transforming recorded events into application-specific experiences.
Applications rarely interact directly with raw accounting records.
Instead they consume projections derived from shared symbolic state.
The general runtime flow is:
Real-world Activity
│
▼
Client Event
│
▼
Identity
│
▼
Permission Evaluation
│
▼
Pitchfork Recording
│
▼
Settlement
│
▼
Symbolic State
│
▼
Projection Selection
│
▼
Client Rendering
Each stage has a distinct responsibility.
Applications record meaningful activity occurring within their own domain.
Events remain factual descriptions of what occurred.
Applications should avoid embedding derived interpretation within events.
Before symbolic information becomes available, the runtime evaluates applicable permissions.
Projection depends upon authorization.
Applications should never assume unrestricted access to symbolic information.
Pitchfork derives symbolic consequences from settled activity.
Different symbolic domains may interpret the same underlying events in different ways while remaining internally consistent.
Applications request projections appropriate to their current task.
Different clients may request different projections over identical symbolic state.
Examples include:
Projection therefore separates accounting from presentation.
Applications remain responsible for presenting information to people.
Rendering includes:
Multiple applications may therefore provide entirely different experiences while sharing the same runtime infrastructure.
The runtime architecture intentionally divides responsibility among several layers.
Clients provide experiences.
The Node Interface provides stable runtime access.
Runtime services provide reusable operational capabilities.
Pitchfork provides symbolic accounting and interpretation.
Nodes provide governance and stewardship.
This separation allows applications to evolve independently while preserving a shared operational foundation throughout the Pancakes ecosystem.
The Pancakes runtime is intentionally application-independent.
Rather than prescribing a single user experience, it provides shared runtime services that support many different kinds of clients.
Each client interprets shared symbolic and operational infrastructure according to its own domain while participating in the same underlying ecosystem.
This separation allows new applications to emerge without requiring changes to the runtime architecture.
Many Pancakes applications support everyday activities.
Examples include:
These applications typically emphasize:
Community-oriented clients help groups coordinate shared activities.
Examples include:
These applications consume shared runtime services for:
Community behaviour emerges through governance rather than application-specific account systems.
Health-related applications require particularly careful treatment of privacy and consent.
Examples include:
The runtime provides:
Applications remain responsible for presenting information in humane and understandable ways.
Some applications interpret symbolic state directly.
Examples include:
These applications typically consume:
Different symbolic clients may present dramatically different experiences while remaining consistent with the same underlying symbolic state.
The runtime also supports applications concerned with places and communities.
Examples include:
These applications frequently combine:
The architecture intentionally remains open to future applications.
Examples might include:
The runtime should accommodate new domains through composition rather than specialized infrastructure.
Not every application requires the same operational safeguards.
Some domains involve information whose disclosure may significantly affect the people involved.
The runtime architecture therefore incorporates privacy and permission as fundamental runtime concerns rather than optional application features.
Applications frequently manage information relating to:
Applications should assume that personal information is private unless explicitly shared.
Households frequently maintain information that is shared among members while remaining private outside the household.
Examples include:
Applications should distinguish household information from both purely personal and fully public information.
Health information often deserves stronger protection than ordinary operational records.
Applications should respect:
The runtime provides permission infrastructure.
Applications remain responsible for humane interaction.
Applications involving children require particularly careful stewardship.
Communities should retain authority over policies governing:
Runtime services should make stronger protections possible without requiring every application to invent independent mechanisms.
Symbolic state may reveal patterns not immediately apparent from individual events.
Examples include:
Applications should treat symbolic projections with the same care afforded to their underlying records.
The runtime architecture assumes that applications may execute across multiple devices while remaining connected to the same node.
Synchronization is therefore a shared runtime responsibility.
Applications should describe desired state while allowing the runtime to manage replication and reconciliation.
Clients should continue functioning whenever practical.
Examples include:
Connectivity expands capability but should not determine whether useful work can occur.
Changes may be synchronized when connectivity becomes available.
Deferred synchronization should preserve:
Applications should avoid assuming immediate communication with remote systems.
Occasionally different devices or participants may modify related information.
The runtime should provide facilities supporting:
Applications may present conflicts differently while sharing common runtime mechanisms.
Because Pitchfork records events rather than application state, nodes may reconstruct symbolic state by replaying historical activity.
Replay supports:
Applications consume reconstructed symbolic state rather than rebuilding it independently.
Different clients may temporarily observe different local views of the same information.
The runtime seeks eventual symbolic consistency while allowing local operation to continue.
Consistency is achieved through shared accounting rather than tightly coupled application synchronization.
Not every client requires continuous communication with a complete Pancakes node.
Some environments benefit from lightweight runtime contexts capable of operating independently before reconnecting.
Virtual nodes provide such an execution environment.
A virtual node represents a temporary or lightweight runtime instance that implements the same runtime contract as a full node while delegating some long-term responsibilities.
Examples include:
Virtual nodes allow applications to remain responsive while preserving compatibility with the broader ecosystem.
Virtual nodes should expose the same conceptual runtime interface as ordinary nodes whenever practical.
Applications should not require separate implementations simply because they execute within a lightweight environment.
Maintaining a consistent runtime contract reduces complexity throughout the ecosystem.
Virtual nodes may temporarily host:
This enables useful work even when disconnected from a full node.
When connectivity becomes available, virtual nodes synchronize with their associated node using the shared runtime synchronization services.
The runtime remains responsible for:
Applications remain responsible only for their own user experience.
Virtual nodes should support movement between devices without compromising continuity.
Users should be able to replace or upgrade devices without losing:
Migration should be an ordinary operational capability rather than an exceptional event.
Virtual nodes extend the runtime architecture.
They do not introduce a second architecture.
Applications should interact with virtual and full nodes through the same conceptual runtime model, allowing deployment flexibility without fragmenting the application ecosystem.
The Pancakes runtime is designed to evolve through composition rather than replacement.
New functionality should ordinarily be introduced by adding:
The runtime itself should remain comparatively stable.
A stable runtime allows independent projects to evolve without continually changing the architectural foundation of the ecosystem.
New applications should integrate with the existing runtime rather than creating independent infrastructure.
A new client should ordinarily:
This allows new projects to become first-class participants in the ecosystem without requiring architectural changes.
Capabilities extend what a node can provide.
Examples include:
Capabilities should expose stable interfaces that may be consumed by many different applications.
Reference services expand shared knowledge available to the ecosystem.
Future examples may include:
Applications should interpret reference information rather than redefining it.
Pitchfork allows new symbolic domains to emerge without changing the runtime architecture.
Examples include:
Applications consume symbolic domains through projections while Pitchfork maintains their underlying consistency.
Applications should remain loosely coupled.
New functionality should normally be implemented through:
Applications should rarely require modification simply because another client has been added to the ecosystem.
The Pancakes architecture intentionally separates responsibilities among a small number of foundational documents.
Each architectural concept should have one canonical home.
The Ecosystem Layers document describes the overall architectural structure of Pancakes.
It explains how:
fit together.
This document defines only the runtime layer.
The Commonwealth Model defines the social and constitutional character of the ecosystem.
It explains:
This runtime architecture assumes those principles without redefining them.
Node Infrastructure defines what a node is.
It describes:
This document assumes the existence of a node and explains how software executes within it.
The Reference Services documentation defines shared information infrastructure.
This runtime architecture explains how applications consume reference services.
It does not redefine them.
The Node Capabilities documentation defines reusable operational services provided by nodes.
This document explains how applications discover and use those capabilities during execution.
Pitchfork provides the ecosystem’s shared symbolic and accounting substrate.
The Pitchfork documentation defines:
This runtime architecture explains how clients interact with those services.
The Client API Specification defines the callable programming interface exposed to applications.
This document explains runtime responsibilities.
The API specification explains how software invokes them.
The Networks documentation explains how independent nodes cooperate.
Examples include:
Networking operates above the runtime architecture defined here.
The runtime architecture is guided by several enduring principles.
Applications define:
Applications should avoid reimplementing shared infrastructure.
Nodes provide:
Applications consume these services rather than replacing them.
Pitchfork provides:
Applications should not create independent symbolic accounting systems.
Governance belongs to people and institutions.
Runtime software enforces governance decisions.
It does not define them.
Applications should only receive projections appropriate to the current user, their permissions, and the governing policies of the node.
Permission evaluation precedes symbolic interpretation.
Projection follows authorization.
New capabilities should be introduced by composing existing runtime services.
Duplicating infrastructure increases complexity and fragments the ecosystem.
Composition preserves interoperability.
Applications, capabilities, and symbolic domains will continue to evolve.
The runtime architecture should evolve more slowly.
Stable foundations encourage:
The Pancakes runtime architecture provides a shared operational foundation upon which many independent applications may coexist.
Rather than defining a single application platform, it defines a cooperative runtime in which applications, symbolic accounting, shared services, and local governance each possess clear responsibilities.
This separation allows:
By maintaining clear boundaries between runtime services, shared accounting, governance, and user experience, the Pancakes ecosystem remains both cohesive and adaptable.
The runtime therefore serves as the operational bridge between locally governed nodes and the diverse applications that support human flourishing throughout the Pancakes Commonwealth.