Architecture Overview

iAm is a monorepo platform for tracking, analyzing, and understanding subjective experiences in real-time. It combines a multi-modal input interface (text, audio, and button-press) with a graph-based data model to support structured measurement of experiential data through STREAM (Structured, Typed, Realtime Experiential Awareness Mapping).

Beta Software

iAm is in early beta. The architecture described here reflects the current state of the system, but components may change as development continues.

Architecture Style

The system follows a monorepo, distributed services architecture with:

• Client-server separation with clear GraphQL API boundaries
• Event-driven architecture for real-time experience reporting
• Cross-platform mobile/web deployment via Capacitor
• Container-first deployment with Kubernetes orchestration
• Graph database-centric data modeling

Tech Stack

Layer	Technology
Frontend	React 18 + TypeScript + Vite + Capacitor (iOS/Android)
Backend	Node.js + Express + Apollo GraphQL Server + TypeScript
Database	Neo4j (Graph Database) with GraphQL integration
Caching/Queues	Redis + BullMQ
Deployment	Docker + Kubernetes (GKE for production)
Build Tool	Yarn Workspaces (monorepo management)
Cloud	Google Cloud Platform (production)

Project Structure

iAm/
├── client/          # React frontend (web + mobile)
│   ├── src/
│   │   ├── pages/       # Route-based page components
│   │   ├── components/  # Reusable UI components
│   │   ├── context/     # React Context providers (auth, session, AI)
│   │   ├── queries/     # Apollo GraphQL queries and mutations
│   │   └── services/    # External service integrations
│   ├── ios/             # Capacitor iOS project
│   └── android/         # Capacitor Android project
├── server/          # Node.js GraphQL API
│   ├── src/
│   │   ├── resources/   # Domain entities (models, resolvers, services)
│   │   ├── server/      # Server init, middleware, GraphQL setup
│   │   ├── services/    # External integrations (email, storage, AI)
│   │   └── utils/       # JWT, migrations, type generation
├── common/          # Shared types and validation schemas
├── docs/            # Documentation
├── scripts/         # Build, deployment, and utility scripts
├── k8s/             # Kubernetes deployment configs
│   ├── local/       # Local K8s development
│   └── production/  # GKE production deployment
└── neo4j/           # Neo4j Docker configuration

Key Modules

Client (/client)

Pattern: Feature-based organization with React Context providers

• src/pages/: Route-based page components organized by feature
• src/components/: Reusable UI components following atomic design principles
• src/context/: React Context providers for global state management (auth, session, system, AI)
• src/services/: External service integrations (GraphQL API, platform detection)
• src/queries/: Apollo GraphQL queries, mutations, and subscriptions organized by domain
• src/database/: Local SQLite database for offline-first capabilities

Server (/server)

Pattern: Resource-based organization following Domain-Driven Design

Each domain entity follows a standardized structure:

resources/ResourceName/
├── inputs/          # GraphQL input types
│   ├── create.input.ts
│   └── query.input.ts
├── outputs/         # GraphQL output types
│   └── output.ts
├── model.ts         # TypeGraphQL model definition
├── resolver.ts      # GraphQL resolvers
└── service.ts       # Business logic

Common (/common)

Shared code between client and server:

• Validation schemas (Yup-based)
• Type definitions used across workspaces
• Utility functions for data transformation

API Boundaries

Endpoint	Protocol	Purpose
/graphql	HTTP	Primary client-server communication
/graphql	WebSocket	Real-time subscriptions for live sessions
/health	HTTP	Service monitoring and load balancer probes
/webhooks/*	HTTP	External service integrations (Stripe, etc.)

State Management

Client-Side

• Apollo Client Cache: GraphQL query results and optimistic updates
• React Context: Global application state (auth, session, system preferences)
• Local Database: Offline-first data persistence with sync capabilities

Server-Side

• Neo4j Graph Database: Primary data persistence with complex relationships
• Redis: Session storage, caching, and job queue state
• Stateless Services: Each API request is independent for horizontal scaling

Deployment Architecture

Development

Docker Compose Stack:
  neo4j-server    # Graph database
  redis           # Caching and queues
  client          # React dev server with hot reload
  web-server      # Node.js with live reload

Production (GKE)

Kubernetes Cluster:
  Ingress Controller   # Global Load Balancer with SSL
  client-deployment    # Nginx serving built React app
  api-deployment       # Node.js GraphQL server
  neo4j-deployment     # Persistent graph database

Design Principles

• Domain-Driven Design: Clear domain boundaries with resources as aggregates
• Graph-First Data Modeling: Neo4j naturally models complex experience relationships
• Type Safety: Strict TypeScript across the entire stack with automated type generation
• Horizontal Scaling: Stateless API enables load balancing; Neo4j supports read replicas
• Offline-First: Local SQLite database and Apollo cache for connectivity independence