Domain Model
iAm's graph-based data model captures the complex, interconnected nature of subjective experience. Built on Neo4j, the system models experiential data through a network of entities and relationships that preserve both the temporal and semantic dimensions of experience reporting.
In the documentation we use Experience Instance and Unique Value for clarity. In the codebase and database schema, these correspond to the Manifestation and Abstract node types respectively.
Why a Graph Database?
Traditional relational databases are not well suited to the fluid, interconnected nature of subjective experience data. iAm uses a graph model because:
- Natural Relationships: Experiences don't exist in isolation -- they reference, investigate, and build upon each other
- Temporal Sequences: The flow of consciousness has inherent ordering
- Semantic Networks: Different experience types share conceptual relationships
- Pattern Analysis: Graph traversals support pattern analysis not readily available in tabular structures
The Entity Hierarchy
Level 1: Users and Observers
User is the account holder who manages authentication, preferences, and account settings. A User owns multiple Observers.
Observer is the entity that actually reports experiences. It represents a specific "lens" or perspective for data collection. Multiple Observers per User enable different research contexts -- for example, a meditation teacher might have separate Observer identities for personal practice vs. research participation.
Level 2: Type Definitions (The Ontology Layer)
These entities form iAm's shared vocabulary for describing consciousness:
| Entity | Purpose | Examples |
|---|---|---|
| ExperienceType | Categories of subjective phenomena | "Verbal Thought", "Emotion", "Visual Imagery", "Bodily Sensation" |
| SessionType | Structure and rules for measurement sessions | Which experience types to track, timing constraints, input methods |
| SequenceType | Ordered combinations of sessions and surveys | Multi-day study protocols, structured practices |
| SurveyType | Questionnaire structures | Pre/post measurements, validated instruments |
Level 3: Version Entities (The Evolution Layer)
Every Type has multiple Versions that track definitional evolution:
- ExperienceTypeVersion: Specific iteration of an experience type definition
- SessionTypeVersion: Specific configuration of a session type
- SurveyTypeVersion: Specific configuration of a survey type with ordered Questions
All versions are immutable once published for research reproducibility. Just as scientific papers cite specific versions of instruments, iAm research can point to exact definitional versions.
Level 4: Measurement Entities (The Data Collection Layer)
| Entity | Description |
|---|---|
| Session | An instance of a SessionTypeVersion being executed. Has start/end times and contains all Experience Instances reported during it. |
| Sequence | An instance of a SequenceTypeVersion. Contains ordered Sessions and Surveys. |
| Survey | An instance of a SurveyTypeVersion being completed. Contains individual Response entities. |
Relationship Types
Core Relationships
| Relationship | Meaning | Example |
|---|---|---|
HAS | Ownership | User HAS Observers, Observer HAS Sessions |
IMPLEMENTS | Type instantiation | Session IMPLEMENTS SessionTypeVersion |
REPORTED | Containment | Session REPORTED Experience Instances |
FOLLOWED_BY | Temporal sequence | Experience Instance FOLLOWED_BY Experience Instance |
INVESTIGATES | Meta-cognitive reflection | Experience Instance INVESTIGATES another Experience Instance |
TO | Direct targeting | Response TO Question |
VERSION / DRAFT | Type evolution | ExperienceType VERSION ExperienceTypeVersion |
Access Control
Every entity with user-facing data supports access control:
- Private: Only the owner can see
- Public: Visible to all platform users
- Shared: Visible to specific groups or studies
Temporal Architecture
Every experience report captures three distinct temporal moments:
| Timestamp | Meaning |
|---|---|
beginInputTimestamp | When the observer starts responding to the experience |
endInputTimestamp | When the observer finishes input (stops typing/releases key) |
submitInputTimestamp | When the user submits the experience instance |
The lag between experience and reporting is itself useful data. These timestamps help researchers understand the temporal dynamics of introspection.
Experience Instances within a session maintain explicit temporal ordering through index values and FOLLOWED_BY relationships, preserving the narrative structure of experience.
Design Trade-offs
Why Separate Unique Value from Experience Instance?
Different observers might report the same experience with slight variations. Unique Values create canonical, normalized representations while preserving raw input. This increases complexity but enables grouping and analysis across observers and time.
Why Three Timestamps?
The gap between experience and reporting contains useful data. Capturing input behavior as part of the measurement enables analysis of reporting latency and introspective dynamics.
Why Versioned Types?
Definitions of consciousness phenomena evolve with research. Immutable versions with clear evolution tracking support research reproducibility at the cost of slightly more complex type management.