add claude
This commit is contained in:
Nuwan
parent
e1c44505ab
commit
278de95a61
|
|
@ -0,0 +1,7 @@
|
|||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(cat:*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue