iAm

Open-source platform for real-time consciousness measurement and subjective experience research.

iAm enables researchers and practitioners to track, analyze, and understand subjective experiences in real-time using a graph-based data model built on Neo4j. It supports Live Experience Reporting (LER) with millisecond temporal precision, validated survey instruments, and version-controlled research protocols.

Key Features

• Real-time experience reporting — Capture subjective experiences as they happen with button-press input, preserving temporal dynamics
• Graph-based data model — Neo4j database captures complex relationships between experiences, sessions, observers, and measurement types
• Version-controlled protocols — Immutable type definitions (SessionTypeVersion, SurveyTypeVersion, ExperienceTypeVersion) enable reproducible research
• Multi-modal measurement — Combines real-time phenomenological data with validated survey instruments (FFMQ, TMS, MDI, and custom scales)
• Cross-platform — Web + mobile (iOS/Android) via Capacitor
• Token-driven design system — Standardized PageShell / PageHeader / Section primitives and ds-* Tailwind tokens; dark mode and runtime accent swap are first-class. See client/src/components/ui/README.md.
• Open science ready — Designed for preregistration, open data sharing, and cross-lab adoption

Tech Stack

• Frontend: React 18 + TypeScript + Vite + Capacitor
• Backend: Node.js + Express + Apollo GraphQL + TypeGraphQL
• Database: Neo4j (Graph Database) + Redis (cache)
• Mobile: Capacitor (iOS/Android)

Quick Start

Prerequisites

• Node.js 18.x (nvm recommended)
• Yarn package manager
• Docker Desktop

Setup

# Clone the repository
git clone https://github.com/clarknoah/iAm.git
cd iAm

# Install dependencies
yarn install

# Set up environment variables
cp .env.example .env
cp server/.env.example server/.env
cp client/.env.example client/.env
cp neo4j/.env.example neo4j/.env

Edit each .env file with your local configuration. See the .env.example files for required variables.

Required Environment Variables

server/.env (minimum):

• NEO4J_URI — Neo4j connection URI (e.g., bolt://localhost:7687)
• NEO4J_USERNAME — Neo4j username
• NEO4J_PASSWORD — Neo4j password
• JWT_TOKEN_SECRET — Secret for JWT authentication
• REFRESH_JWT_TOKEN_SECRET — Secret for refresh tokens

client/.env (minimum):

• VITE_GRAPHQL_ENDPOINT — GraphQL API URL (default: http://localhost:3331/graphql)

Running

Start the database, server, and client in separate terminals:

# Terminal 1: Database
yarn neo4j:docker:start

# Terminal 2: Server
cd server && yarn dev

# Terminal 3: Client
cd client && yarn dev

Access the app at http://localhost:3330

Project Structure

iAm/
├── client/          # React frontend (web + mobile)
├── server/          # GraphQL API backend
├── common/          # Shared types and utilities
├── docs/            # Documentation
│   ├── ARCHITECTURE.md   # System architecture
│   ├── CONCEPTS.md       # Core domain concepts
│   └── STANDARDS.md      # Development standards
└── k8s/             # Kubernetes deployment configs

Documentation

• Architecture Overview — System design, data flow, deployment
• Core Concepts — Domain model, entity relationships, measurement philosophy
• Development Standards — Coding conventions, patterns, testing
• Contributing Guide — How to contribute
• Security Policy — Reporting vulnerabilities

Development Commands

yarn launch-all          # Start all services (Neo4j, Redis, client, server)
yarn kill-all            # Stop everything

# Type generation (run after schema changes)
cd server && yarn build:types:all

# Testing
cd client && yarn test          # Client unit tests
cd client && yarn test:e2e      # Client E2E tests
cd server && yarn test:e2e      # Server E2E tests

# Build & validate
yarn build                      # Build everything
yarn typecheck                  # TypeScript checking
yarn format                     # Format code

Mobile Deployment

iAm supports iOS and Android via Capacitor.

iOS (TestFlight):

1. Ensure VITE_GRAPHQL_ENDPOINT points to production
2. Run yarn cap:all:update
3. Open in Xcode: Product > Archive > Deploy to App Store

Android (Internal Testing):

1. Update build.gradle version number
2. Open Android Studio: Build > Generate Signed App Bundle

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for details.

This means:

• You can use, modify, and distribute this software
• If you modify and deploy it as a network service, you must make your source code available
• Any derivative works must also be licensed under AGPL-3.0