How PMFA works

A technical deep dive into the architectural decisions that make PMFA different.

Core concepts

Facts, not records

PMFA doesn't store "records" that can be edited. It stores facts — immutable statements about what happened.

A fact includes:

• What: The type of event (e.g., "work order created")
• When: Server-controlled timestamp (UTC)
• Who: The authenticated actor (user or system)
• Authority: The permission that authorized this action
• Payload: The data (e.g., work order details)
• Links: References to prior facts (forming chains)

Once written, a fact cannot be changed. It can only be superseded or revoked by a new fact.

Mutations, not updates

When something needs to change (e.g., client changes an order), PMFA doesn't update the existing record. It creates a mutation — a new fact that references the old one.

Example:

Both facts remain in the system. The "current state" is the most recent non-revoked fact.

Registry-driven schemas

PMFA uses a registry to define what types of facts exist and what they contain.

Example registry entry for "work order":

{
  "entity": "work_order",
  "fields": [
    {"name": "client", "type": "ref:client", "required": true},
    {"name": "description", "type": "text", "required": true},
    {"name": "quantity", "type": "integer", "required": true},
    {"name": "due_date", "type": "date", "required": false}
  ],
  "authority_required": "workshop.create_work_order"
}

The UI, validation, and API are generated from this schema. Change the schema, and the entire system adapts.

Authority chains

Every action requires explicit authority. Authority is granted via roles and permissions.

Example:

• User "John" has role "Workshop Manager"
• Role "Workshop Manager" has permission "workshop.create_work_order"
• When John creates a work order, the fact records his authority chain

If John's role is revoked, past actions remain valid (they had authority at the time), but new actions are blocked.

Evidence chains

Facts form chains by referencing prior facts. A chain represents the complete history of an entity.

Example: Work order lifecycle

This chain can be exported as evidence, proving the entire timeline.

Revocation

When something is invalidated, PMFA adds a revocation fact to the chain.

The original work order (f_001) remains in the system, but its state is now "revoked."

System layers

1. Registry layer

Defines schemas, entities, fields, and authority requirements. Stored as immutable facts themselves.

2. Fact store

Append-only database. Facts are written but never updated or deleted. Optimized for time-series queries.

3. Projection layer

Reads facts and computes "current state" views (e.g., "show me all active work orders"). Projections are cached and regenerated from facts when needed.

4. Authority engine

Evaluates whether an actor has permission to perform an action. Logs all authorization decisions.

5. Evidence generator

Reads fact chains and exports them as PDFs, JSON, or other formats. Includes cryptographic verification data.

Why this architecture?

• Accountability: Every action is traceable to an actor and authority
• Auditability: Complete history is preserved forever
• Legal defensibility: Evidence chains can be presented in court
• Flexibility: Registry changes don't require code rewrites
• Correctness: Immutability prevents data corruption or manipulation