Installation Guide

Complete setup instructions for the iAm consciousness measurement platform.

Prerequisites

Before starting, ensure you have the following installed:

Requirement	Version	Notes
Node.js	>= 24.x	Use nvm for version management
Yarn	1.x (Classic)	npm install -g yarn
Docker Desktop	Latest	Required for Neo4j and Redis containers
Git	Latest	For cloning the repository
tmux (optional)	Latest	Used by yarn launch-all to run all services in one terminal

Verify Prerequisites

node --version    # Should print v24.x or higher
yarn --version    # Should print 1.x
docker --version  # Should print Docker version 2x.x+
git --version

Step-by-Step Setup

1. Clone and Install Dependencies

git clone https://github.com/clarknoah/iAm.git
cd iAm
yarn install

Yarn will install dependencies for all three workspaces (client, server, common) and run any post-install hooks including patch-package.

2. Environment Variables

Copy all example environment files:

cp .env.example .env
cp server/.env.example server/.env
cp client/.env.example client/.env
cp neo4j/.env.example neo4j/.env

Root .env

Contains Neo4j Docker configuration and build variables. At minimum, set:

# Neo4j Docker container settings
NEO4J_DOCKER_VERSION=2025.01.0
NEO4J_DOCKER_NAME=iam-neo4j-dev
NEO4J_DOCKER_USER=neo4j
NEO4J_DOCKER_PASSWORD=your_secure_password

# Volume mount paths
NEO4J_DOCKER_DATA=./neo4j/data
NEO4J_DOCKER_IMPORT=./neo4j/import
NEO4J_DOCKER_LOGS=./neo4j/logs

server/.env

Contains the API server configuration. Required variables:

# Database connection (must match your Neo4j Docker settings)
DB_URI=bolt://localhost:7687
DB_USER=neo4j
DB_PASSWORD=your_secure_password    # Same as NEO4J_DOCKER_PASSWORD

# Authentication secrets (generate with: openssl rand -base64 64)
JWT_TOKEN_SECRET=your_jwt_secret_here
REFRESH_JWT_TOKEN_SECRET=your_refresh_secret_here

All other server variables have sensible defaults for local development. See server/.env.example for the full list.

client/.env

Contains the frontend configuration. The defaults work for local development:

VITE_GRAPHQL_ENDPOINT=http://localhost:3331/graphql
VITE_WS_ENDPOINT=ws://localhost:3331/graphql

neo4j/.env

Contains Neo4j-specific configuration used by Docker Compose:

NEO4J_AUTH=neo4j/your_secure_password
NEO4J_PLUGINS=["apoc", "graph-data-science"]

3. Start Neo4j Database

Neo4j can be run via Docker (recommended) or as a local installation.

Docker (Recommended)

yarn neo4j:docker:start

This reads your root .env file and either creates a new container or starts an existing one named iam-neo4j-dev. Neo4j will be available at:

• Browser: http://localhost:7474 (Neo4j Browser UI)
• Bolt: bolt://localhost:7687 (application connection)

To verify Neo4j is running:

docker ps | grep neo4j

To stop Neo4j:

yarn neo4j:docker:stop

4. Start Redis (Optional)

Redis is used for caching and background job queues (BullMQ). For basic local development it is optional, but required for full functionality.

Docker

yarn redis:docker:start

Redis will be available at localhost:6379.

macOS (Homebrew)

brew install redis
yarn redis:local:start

5. Start the Server

cd server
yarn dev

The GraphQL API server starts on http://localhost:3331. You can access the Apollo GraphQL Playground at http://localhost:3331/graphql.

Wait for the server to fully start (you will see log output indicating it is listening) before starting the client.

6. Start the Client

In a separate terminal:

cd client
yarn dev

The client dev server starts on http://localhost:3330 with hot module reloading.

7. Run All Services at Once (Alternative)

Instead of starting services in separate terminals, you can use the tmux launcher:

yarn launch-all

This creates a tmux session with five panes running:

1. A free terminal for commands
2. Neo4j Docker container
3. Client dev server
4. Tailwind CSS watcher
5. API server (starts after a short delay to allow Neo4j to initialize)

Useful tmux commands:

• yarn attach-tmux -- Reattach to the session
• yarn kill-all -- Stop all services and close the session
• Ctrl-b <arrow> -- Navigate between panes
• Ctrl-b z -- Zoom into/out of a pane

Type Generation

After any changes to the GraphQL schema (models, inputs, outputs, resolvers), regenerate TypeScript types:

cd server
yarn build:types:all

This can take 1-2 minutes. Do not interrupt the process or create temporary type workarounds. The generated types propagate from the server to the client.

Database Migrations

To create and run Neo4j migrations:

# Create a new migration
yarn migration:create

# Test draft migrations
yarn migration:drafts:test

# Commit draft migrations
yarn migration:drafts:commit

# Commit published migrations
yarn migration:published:commit

Building for Production

Full Build

yarn build

This runs the server TypeScript compilation and client Vite build in parallel.

Docker Images

Build and push production Docker images:

# Client image
yarn client:docker:build:amd    # AMD64 only
yarn client:docker:build:arm    # ARM64 only
yarn client:docker:build:both   # Multi-platform

# Server image
yarn server:docker:build        # Multi-platform

Mobile Setup (Capacitor)

iAm supports iOS and Android via Capacitor. This requires additional platform-specific tooling.

iOS

Requirements: macOS with Xcode installed, Apple Developer account.

cd client
yarn build:capacitor
npx cap sync ios
npx cap open ios

Android

Requirements: Android Studio with SDK installed.

cd client
yarn build:capacitor
npx cap sync android
npx cap open android

Testing

# Client unit tests (Vitest)
cd client && yarn test

# Run a specific client test
cd client && yarn test ComponentName

# Client E2E tests (Playwright)
cd client && yarn test:e2e

# Server E2E tests
cd server && yarn test:e2e

# TypeScript type checking
yarn typecheck

# Code formatting
yarn format

Common Issues

Neo4j Container Won't Start

1. Verify Docker Desktop is running: docker ps
2. Check that the root .env file has all NEO4J_DOCKER_* variables set
3. Ensure ports 7474 and 7687 are not already in use
4. Check container logs: docker logs iam-neo4j-dev

Server Fails to Connect to Neo4j

1. Verify Neo4j is running: docker ps | grep neo4j
2. Check that DB_URI in server/.env matches the Neo4j port (default: bolt://localhost:7687)
3. Check that DB_USER and DB_PASSWORD match the Neo4j credentials

GraphQL Type Generation Errors

Common causes:

• Using @Field(() => Date) instead of @Field((type) => GraphQLDateTime) from graphql-scalars
• Using raw model classes in output types instead of Output classes

Port Already in Use

# Find the process using the port
lsof -i :3330   # client
lsof -i :3331   # server
lsof -i :7687   # neo4j

# Kill it
kill -9 <PID>