SocialluxSociallux
Toggle navigation menu
common.actions.homeStudioLog in
Docs navigationv

Docs

Atoms

An atom represents a thing in the material or digital world. Atoms are flexible records that may hold any shape of data — a person, a product, a note, an event, or anything else you need to model.

Anatomy

Every atom shares the same base structure regardless of what it represents. The data field is where content lives; the rest of the fields govern access, identity, and lifecycle.

Field — the key name as it appears in the API request and response.

Description — what the field controls and when to use it.

Default — the value used when the field is omitted on create. required means the field must always be provided and has no fallback.

Field

data

Record<string, FieldEntry>

Description

The primary content of the atom. A flexible key/value map where each value is either a plain string or an object with a required value property and optional metadata.

Default

{}

Field

lexemeIds

ObjectId[]

Description

The lexemes this atom subscribes to. A lexeme describes what the atom represents — its schema, field names, and expected interactions. An atom can subscribe to multiple lexemes simultaneously.

Default

[]

Field

owner

ObjectId → User

Description

The user who created and controls the atom. The owner controls who can read, edit, and manage the atom. Ownership is always explicit — there are no ownerless atoms.

Default

required

Field

sharedWith

{ user: ObjectId, role: 'reader' | 'editor' }[]

Description

Explicit per-user access grants. A reader can view the atom; an editor can update its data and lexeme subscriptions. Sharing does not transfer ownership.

Default

[]

Field

isPublic

boolean

Description

When true, the atom is readable by anyone — including unauthenticated users. Useful for publishable content. Does not affect write access.

Default

false

Field

version

number

Description

Auto-incremented each time data, lexemeIds, or sharedWith is modified. Useful for detecting stale reads and supporting optimistic concurrency.

Default

1

Field

deleted

boolean

Description

Soft-delete flag. Deleted atoms are hidden from standard queries but not erased from the database. Owners can restore a soft-deleted atom.

Default

false

Examples

The same atom structure accommodates very different kinds of things. Below are six common patterns to illustrate how the data field adapts to different domains.

Person / Identity

Captures the core identity of a person — name, contact, and a brief bio. A person atom might subscribe to a personal-identity lexeme that defines exactly which fields are expected.

{
  "data": {
    "firstName": {
      "value": "Ada"
    },
    "lastName": {
      "value": "Lovelace"
    },
    "email": {
      "value": "ada@example.com"
    },
    "bio": {
      "value": "Mathematician and writer, often regarded as the first computer programmer."
    }
  }
}

Product / Item

Describes a physical or digital product with pricing and availability details. Could subscribe to a product lexeme that standardizes field names across a marketplace.

{
  "data": {
    "name": {
      "value": "Mechanical Keyboard"
    },
    "sku": {
      "value": "MK-2040-BLK"
    },
    "price": {
      "value": "149.00"
    },
    "currency": {
      "value": "USD"
    },
    "inStock": {
      "value": "true"
    },
    "description": {
      "value": "Compact 65% layout, tactile switches, PBT double-shot keycaps."
    }
  }
}

Journal Entry / Note

A timestamped personal note or journal entry. Minimal structure — mostly free text. Subscribing to a journal-entry lexeme would let apps surface all entries in chronological order.

{
  "data": {
    "title": {
      "value": "First day with the new setup"
    },
    "body": {
      "value": "Got the standing desk assembled. Took about two hours but it feels worth it. Writing feels different at eye level."
    },
    "mood": {
      "value": "calm"
    }
  }
}

Task / To-Do

A unit of work with a status, due date, and priority. A task lexeme could define the allowed values for status and priority, enabling consistent filtering across a workspace.

{
  "data": {
    "title": {
      "value": "Finalize API documentation"
    },
    "status": {
      "value": "in-progress"
    },
    "priority": {
      "value": "high"
    },
    "dueDate": {
      "value": "2026-05-01"
    },
    "assignee": {
      "value": "user_abc123"
    }
  }
}

Event

A scheduled occurrence — a meeting, launch, milestone, or deadline. An event lexeme could expose an interactions field that defines how AI assistants should handle scheduling conflicts.

{
  "data": {
    "name": {
      "value": "Product Review — Q2"
    },
    "startAt": {
      "value": "2026-05-15T14:00:00Z"
    },
    "endAt": {
      "value": "2026-05-15T15:00:00Z"
    },
    "location": {
      "value": "https://meet.example.com/q2-review"
    },
    "description": {
      "value": "Quarterly product review with stakeholders and engineering."
    }
  }
}

Meta / Collection

An atom that references other atoms by their IDs. This is how Sociallux models collections, playlists, reading lists, and any other ordered or grouped set of things — without duplicating the underlying data.

{
  "data": {
    "title": {
      "value": "Resources for onboarding"
    },
    "description": {
      "value": "A curated set of atoms to share with new team members during their first week."
    },
    "atomIds": {
      "value": "atom_id_1, atom_id_2, atom_id_3"
    }
  }
}

What comes next

Atoms gain semantic meaning through lexemes. A lexeme defines the expected fields of an atom, provides human-readable labels, and can specify the valid interactions on that atom — including how AI agents are permitted to work with it. A single atom can subscribe to multiple lexemes at once.