From 278de95a611448ac34a296ec2f4ec45a19fbded5 Mon Sep 17 00:00:00 2001
From: Nuwan <nuwanchaturanga@gmail.com>
Date: Tue, 6 Jan 2026 14:58:35 +0530
Subject: [PATCH] add claude

---
 .claude/settings.local.json |   7 +
 CLAUDE.md                   | 294 ++++++++++++++++++++++++++++++++++++
 2 files changed, 301 insertions(+)
 create mode 100644 .claude/settings.local.json
 create mode 100644 CLAUDE.md

diff --git a/.claude/settings.local.json b/.claude/settings.local.json
new file mode 100644
index 000000000..c5ce08306
--- /dev/null
+++ b/.claude/settings.local.json
@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(cat:*)"
+    ]
+  }
+}
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..ec1688a2a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,294 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## System Architecture
+
+JamKazam is a real-time music collaboration platform with a service-oriented architecture:
+
+**Core Services:**
+- **jam-ui**: React 16.x frontend SPA (port 4000)
+- **web**: Rails 4.2.8 backend API (port 3000)
+- **admin**: Rails 4.2.8 admin portal with ActiveAdmin
+- **websocket-gateway**: EventMachine-based WebSocket server for real-time communication
+- **ruby**: Shared business logic gem (`jam_ruby`)
+- **pb**: Protocol Buffer definitions for WebSocket messaging
+- **db**: PostgreSQL schema migrations (pg_migrate)
+
+**Communication:**
+- jam-ui ↔ web: REST API (`/api/*` endpoints)
+- jam-ui ↔ websocket-gateway: WebSocket with Protocol Buffers
+- Services ↔ Database: Single shared PostgreSQL database
+- Async messaging: RabbitMQ/AMQP between services
+- Background jobs: Resque with Redis
+
+**Technology Stack:**
+- Ruby 2.3.1 (pinned, with noted upgrade path to 2.5+)
+- Rails 4.2.8
+- React 16.13.1
+- PostgreSQL
+- Redis (Resque job queue)
+- RabbitMQ (AMQP messaging)
+- EventMachine (async I/O)
+- Protocol Buffers (real-time messaging)
+
+## Development Setup
+
+### Prerequisites
+
+**Local hosts configuration:**
+```
+127.0.0.1 www.jamkazam.local     # Rails web app
+127.0.0.1 beta.jamkazam.local    # React app
+```
+
+**Database setup:**
+```bash
+createdb jam_ruby
+cd ruby
+bundle exec jam_db up --connopts=dbname:jam host:localhost user:postgres password:postgres
+```
+
+### Environment Configuration
+
+Copy jam-ui environment example:
+```bash
+cd jam-ui
+cp .env.development.example .env.development.local
+# Edit .env.development.local with your local settings
+```
+
+### Installing Dependencies
+
+**Protocol Buffers (required first):**
+```bash
+cd pb
+./build
+```
+
+**Ruby gem (shared library):**
+```bash
+cd ruby
+bundle install
+./migrate.sh
+```
+
+**Web (Rails API):**
+```bash
+cd web
+bundle install
+```
+
+**Admin (Rails admin portal):**
+```bash
+cd admin
+bundle install
+```
+
+**WebSocket Gateway:**
+```bash
+cd websocket-gateway
+bundle install
+```
+
+**React frontend:**
+```bash
+cd jam-ui
+npm install
+```
+
+## Common Commands
+
+### Running Services
+
+**React frontend:**
+```bash
+cd jam-ui
+npm run start
+# Runs on http://beta.jamkazam.local:4000
+```
+
+**Rails web API:**
+```bash
+./runweb
+# or manually:
+cd web
+bundle exec rails s
+# Runs on http://www.jamkazam.local:3000
+```
+
+**Admin portal:**
+```bash
+./runadmin
+# or manually:
+cd admin
+bundle exec rails s
+```
+
+**Background job workers:**
+```bash
+./runjobs
+# or manually:
+cd web
+bundle exec rake all_jobs
+```
+
+**WebSocket gateway:**
+```bash
+cd websocket-gateway
+# Start via appropriate launch script
+```
+
+### Building
+
+**Build all services:**
+```bash
+./build
+```
+
+**Build individual services:**
+```bash
+# Protocol buffers
+cd pb
+./build
+
+# Ruby gem
+cd ruby
+./build
+
+# Web
+cd web
+./jenkins  # CI build script
+
+# Admin
+cd admin
+./jenkins
+
+# WebSocket gateway
+cd websocket-gateway
+./jenkins
+
+# React frontend
+cd jam-ui
+npm run build
+```
+
+### Testing
+
+**Run all tests:**
+```bash
+./runtests
+```
+
+**Individual service tests:**
+```bash
+# Ruby gem tests
+cd ruby
+bundle exec rspec
+
+# Web tests
+cd web
+bundle exec rspec
+
+# Admin tests
+cd admin
+bundle exec rspec
+
+# WebSocket gateway tests
+cd websocket-gateway
+bundle exec rspec
+
+# React tests
+cd jam-ui
+npm test  # Runs Playwright tests
+```
+
+**JavaScript unit tests (legacy):**
+```bash
+# Start web server, then visit:
+# http://localhost:3000/teaspoon
+```
+
+### Database Migrations
+
+**Run migrations:**
+```bash
+cd ruby
+./migrate.sh
+```
+
+**Create migration:**
+Migrations use `pg_migrate` (not Rails migrations). Add new `.sql` files to `db/up/` directory.
+
+**Reset database:**
+```bash
+./resetdb.sh
+```
+
+### Code Style
+
+**SCSS compilation:**
+```bash
+cd jam-ui
+npm run scss
+```
+
+## Development Patterns
+
+### Naming Conventions
+
+**React components:** Prefix with `JK` (e.g., `JKMusicSessions`, `JKDashboardMain`)
+
+**Component files:** Follow the pattern: `src/components/{category}/JK{ComponentName}.js`
+
+### Local vs Production Gems
+
+The Gemfiles use conditional logic:
+- **Development:** Uses local paths (`:path => "../ruby"`)
+- **CI/Production:** Uses gem server with build numbers
+
+When working locally, gem dependencies automatically resolve to sibling directories.
+
+### Protocol Buffers
+
+When modifying Protocol Buffer definitions:
+1. Edit `pb/src/client_container.proto`
+2. Run `cd pb && ./build`
+3. Generated Ruby bindings go to `pb/target/ruby/jampb`
+4. All services automatically pick up changes via local gem path
+
+### Routes and API
+
+**React routes:** Defined in `jam-ui/src/components/dashboard/JKDashboardMain.js`
+
+**Rails API routes:**
+- Web: `web/config/routes.rb`
+- Admin: `admin/config/routes.rb`
+
+### Session Authentication
+
+React app uses session-based authentication from Rails:
+- Looks for `remember_token` cookie
+- Shares session between `www.jamkazam.local` and `beta.jamkazam.local`
+- Redirects to Rails sign-in if unauthenticated
+
+## Important Notes
+
+### Ruby Version Constraints
+
+Many gems are pinned to support Ruby 2.3.1. Comments indicate "pinned until we are on ruby 2.5; then remove". When upgrading Ruby version, check Gemfiles for pinned versions to update.
+
+### Memory Leak Prevention
+
+The codebase has had memory leak issues. When working with:
+- WebSocket listeners: Ensure proper cleanup in component unmount
+- Global window objects: Avoid polluting global scope
+- Event handlers: Always remove listeners on cleanup
+
+### Build System
+
+The project uses custom build scripts (`./build`, `./jenkins`) rather than standard Rails/npm conventions. These orchestrate builds across all services and handle packaging for deployment.
+
+### Test Database
+
+Uses PostgreSQL with `pg_migrate` for schema management. Database name is `jam` for development.