Introduction to Frois and Core Principles

TL;DR

Frois helps you organize interconnected data by treating everything as a "fact" and structuring it with clear relationships. It focuses on immutability and precise querying to ensure your data stays consistent and easy to explore. Understanding Frois means thinking about your data as a set of verifiable, linked statements.

1. The Mental Model

Imagine you're building a massive, interconnected knowledge graph. Instead of tables or documents, you're constantly adding small, confirmed pieces of information, and linking them together. This graph grows over time, but past information never changes, only new connections or facts are added.

2. The Core Material

Frois is a system for managing data that's designed for immutability, traceability, and interconnection. It's built on a few core principles that guide how you structure, store, and query your information.

What is a "Fact"?

In Frois, the smallest unit of information is a fact. A fact isn't just a row in a table or a field in a document; it's a statement about a relationship or an attribute. This statement typically involves an entity, an attribute, and a value.

For example, instead of a user object { "id": 123, "name": "Alice" }, Frois sees two facts:
[entity ID 123, has_name, "Alice"]
[entity ID 123, is_type, "User"]

These facts are just positive assertions. You don't delete facts; you assert new facts that might contradict old ones or add new information. This is called immutability – once a fact is recorded, it's never removed. This makes auditing and understanding data changes much simpler.

Entities, Attributes, and Values

• Entity: This is the 'thing' you're talking about – a user, a product, a specific event. Entities are identified by a unique ID.
• Attribute: This describes a property or relationship of an entity. Think of it as a "field name" or a "predicate".
• Value: This is the data associated with the attribute for that entity. It can be a string, number, boolean, or even another entity ID.

Together, an entity-attribute-value (EAV) triplet forms a fact. Sometimes you'll see this called an "eavt" tuple where 't' stands for transaction time, indicating when the fact was asserted.

How Data Changes (and doesn't)

Since facts are immutable, when you "update" data in Frois, you're actually asserting new facts that might supersede older ones. Frois keeps a history of all facts. This means you can always query your data as it existed at any point in time.

Let's say entity ID 123 initially had has_name, "Alice".
If you update their name to "Alicia":
You don't change [123, has_name, "Alice"]. Instead, you assert a new fact:
[123, has_name, "Alicia"]

When you query for entity ID 123's name, Frois will give you the most recent valid fact for that attribute. However, you can still query for the name at a specific past time and see "Alice".

Referencing Other Entities

A key strength is how facts link entities. A value can itself be an entity ID, establishing relationships between different "things."

For example:
[entity ID 123 (User), has_purchased, entity ID 456 (Product)]
[entity ID 456 (Product), named, "Cool Gadget"]

This builds a rich, interconnected graph of your data.

3. Worked Example

Let's track a simple task management system using Frois principles.

First, we define some attributes:
task/name (a string)
task/status (an enum, e.g., :status/todo, :status/done)
task/assigned_to (an entity ID, linking to a user)

Now, let's represent some actions:

1. Create a New Task:
   Say we automatically generate a new entity ID for a task, let's call it task_001.
   We'd assert these facts:
   [task_001, task/name, "Write report"]
[task_001, task/status, :status/todo]

2. Assign the Task to a User:
   Assume user_A is an existing user entity.
   [task_001, task/assigned_to, user_A]

3. Complete the Task:
   [task_001, task/status, :status/done]

Notice we didn't "update" the task/status fact. We asserted a new fact for task_001's status. When you query for task_001's current status, Frois would retrieve :status/done because it's the latest assertion for that attribute on that entity. If you needed to see who it was assigned to before it was completed, Frois allows precise time travel querying.

4. Key Takeaways

• Frois treats all data as immutable "facts" comprised of an entity, attribute, and value.
• Data "updates" in Frois are new facts that supersede older ones, preserving a full history.
• Entities are uniquely identified and can be values for other facts, allowing deep interconnections.
• The system provides full traceability, letting you see the state of your data at any point in time.
• Frois excels at modelling complex, evolving relationships and audit trails.
• It provides a graph-like structure without relying on traditional graph database technologies alone.

Common Mistakes to Avoid:
- Thinking about "deleting" data; instead, you assert facts that mark data as inactive or supersede it.
- Trying to model everything as a flat table; embrace the interconnected entity graph.
- Forgetting that every fact has a temporal dimension; use it for audit and historical queries.
- Overlooking the importance of unique entity IDs for every "thing" in your system.

5. Now Try It

Spend 15 minutes thinking about a simple domain you know well (e.g., managing a book collection, tracking grocery items, or planning a simple trip). For three key "things" in that domain (e.g., a "Book", a "User", a "Publisher"), list out 3-5 attributes each might have. Then, describe 2-3 common actions (like "add book," "mark book read," "loan book to user") and write down the Frois-style facts you would assert to represent those actions and their resulting data. What does "undoing" an action look like in terms of facts?