# Codebase Structure

**Analysis Date:** 2026-01-11

## Directory Layout

```
jam-cloud/
├── jam-ui/                          # React SPA frontend (port 4000)
├── web/                             # Rails 4.2.8 API backend (port 3000)
├── admin/                           # Rails admin portal (ActiveAdmin)
├── websocket-gateway/               # EventMachine WebSocket server
├── ruby/                            # Shared business logic gem (jam_ruby)
├── pb/                              # Protocol Buffer definitions
├── db/                              # PostgreSQL migrations (403+ files)
├── lambda/                          # AWS Lambda functions
├── monitor/                         # Monitoring/observability
├── wordpress/                       # WordPress integration
├── CLAUDE.md                        # Development documentation
└── .planning/                       # GSD project planning
```

## Directory Purposes

**jam-ui/**
- Purpose: Modern React 16 frontend SPA
- Contains: React components, hooks, Redux store, helpers, layouts
- Key files: `src/index.js` (entry), `src/App.js` (root), `package.json` (deps)
- Subdirectories:
  - `src/components/` - 47 component directories (auth, client, dashboard, jamtracks, feed, common, etc.)
  - `src/hooks/` - 41 custom React hooks
  - `src/helpers/` - 22 utility files (rest.js, apiFetch.js, MixerHelper.js, JamServer.js)
  - `src/store/` - Redux Toolkit setup with 12 feature slices
  - `src/layouts/` - 18 layout components
  - `src/context/` - 18 Context API providers

**web/**
- Purpose: Rails 4.2.8 REST API backend
- Contains: Controllers (83 API), models (via ruby gem), views (legacy), mailers
- Key files: `config/routes.rb` (51KB), `config/application.rb` (534 lines of config)
- Subdirectories:
  - `app/controllers/` - 83 API controller files
  - `app/views/` - 71 view directories (legacy Rails views)
  - `config/initializers/` - 26 initialization files
  - `spec/` - RSpec tests

**ruby/**
- Purpose: Shared business logic gem (jam_ruby)
- Contains: ActiveRecord models, managers, validators, message factory
- Key files: `lib/jam_ruby.rb` (gem manifest), `lib/jam_ruby/message_factory.rb` (42KB)
- Subdirectories:
  - `lib/jam_ruby/models/` - 217 model files (User, MusicSession, JamTrack, Recording, etc.)
  - `lib/jam_ruby/lib/` - 29 manager/utility files
  - `lib/jam_ruby/amqp/` - Message queue handlers
  - `lib/jam_ruby/resque/` - Background job definitions

**websocket-gateway/**
- Purpose: Real-time WebSocket communication server
- Contains: EventMachine-based server, WebSocket protocol handling
- Key files: Gemfile (dependencies), lib/ (implementation)
- Subdirectories: `spec/` for RSpec tests

**pb/**
- Purpose: Protocol Buffer message definitions
- Contains: `.proto` source files, generated Ruby/JavaScript bindings
- Key files: `src/client_container.proto` (WebSocket message types)
- Subdirectories:
  - `target/ruby/jampb/` - Generated Ruby Protocol Buffer classes
  - `target/javascript/` - Generated JavaScript bindings

**admin/**
- Purpose: Rails admin portal with ActiveAdmin
- Contains: Admin controllers, configurations, views
- Key files: Gemfile (includes activeadmin), config/
- Subdirectories: Same structure as Rails web service

**db/**
- Purpose: Database schema and migrations
- Contains: 403+ migration files in `up/` directory
- Key files: `build` (migration runner), `manifest` (migration manifest)
- Subdirectories: `up/` - All migration SQL/Ruby files

## Key File Locations

**Entry Points:**
- `jam-ui/src/index.js` - React DOM render entry
- `jam-ui/public/index.html` - HTML template with `<div id="main">`
- `web/config/routes.rb` - Rails route definitions (51KB)
- `web/config/application.rb` - Rails configuration (534 lines)
- `ruby/lib/jam_ruby.rb` - Shared gem manifest

**Configuration:**
- `jam-ui/.env.development`, `.env.staging`, `.env.production` - Frontend environment config
- `jam-ui/.eslintrc.json` - ESLint configuration
- `jam-ui/.prettierrc` - Prettier formatting rules
- `jam-ui/package.json` - Node dependencies and scripts
- `web/config/database.yml` - PostgreSQL connection config
- `web/config/environments/*.rb` - Rails environment-specific settings
- `*/Gemfile`, `*/Gemfile.alt` - Ruby gem dependencies (Gemfile.alt for M1 Macs)

**Core Logic:**
- `jam-ui/src/components/` - All React components
- `jam-ui/src/helpers/rest.js` - 70+ API operation functions (945 lines)
- `jam-ui/src/helpers/MixerHelper.js` - Audio mixer logic (1,270 lines)
- `jam-ui/src/hooks/useJamServer.js` - WebSocket orchestration (26KB)
- `web/app/controllers/` - All Rails API controllers
- `ruby/lib/jam_ruby/models/` - All business logic models

**Testing:**
- `jam-ui/tests/` - React tests (Playwright, Jest)
- `jam-ui/playwright.config.ts` - Playwright E2E config
- `web/spec/` - Rails RSpec tests
- `web/spec/javascripts/` - Legacy Jasmine tests with Karma
- `ruby/spec/` - Ruby gem RSpec tests

**Documentation:**
- `CLAUDE.md` - Project documentation for Claude Code
- `README.md` - Project setup and usage (root and service-level)

## Naming Conventions

**Files:**
- React components: `JK{ComponentName}.js` (e.g., `JKDashboardMain.js`, `JKSessionModal.js`)
- Non-JK components: `PascalCase.js` (e.g., `Avatar.js`, `FalconCardHeader.js`)
- React hooks: `use{Feature}.js` (e.g., `useJamServer.js`, `useGearUtils.js`)
- Helpers: `camelCase.js` (e.g., `apiFetch.js`, `rest.js`, `utils.js`)
- Rails controllers: `api_{resource}_controller.rb` (e.g., `api_sessions_controller.rb`)
- Ruby models: `snake_case.rb` (e.g., `user.rb`, `music_session.rb`, `jam_track.rb`)
- Test files: `*.test.js` (Jest), `*.spec.js` (Jasmine), `*.spec.rb` (RSpec), `*.spec.ts` (Playwright)

**Directories:**
- React: kebab-case or camelCase (e.g., `components/`, `dashboard/`, `jamtracks/`)
- Rails: snake_case (e.g., `app/controllers/`, `config/initializers/`)
- Ruby: snake_case (e.g., `lib/jam_ruby/models/`)

**Special Patterns:**
- `index.js` - Barrel exports or entry points
- `*_controller.rb` - Rails controllers
- `*_spec.rb` - RSpec test files
- `*.proto` - Protocol Buffer definitions

## Where to Add New Code

**New React Feature:**
- Primary code: `jam-ui/src/components/{category}/JK{FeatureName}.js`
- State management: `jam-ui/src/store/features/{feature}Slice.js`
- API calls: Add functions to `jam-ui/src/helpers/rest.js`
- Custom hooks: `jam-ui/src/hooks/use{Feature}.js`
- Tests: `jam-ui/tests/{category}/{feature}.test.js`

**New API Endpoint:**
- Controller: `web/app/controllers/api_{resource}_controller.rb`
- Routes: Add to `web/config/routes.rb`
- Business logic: `ruby/lib/jam_ruby/models/{model}.rb`
- Tests: `web/spec/controllers/api_{resource}_controller_spec.rb`

**New Model/Business Logic:**
- Model definition: `ruby/lib/jam_ruby/models/{model_name}.rb`
- Tests: `ruby/spec/jam_ruby/models/{model_name}_spec.rb`

**New WebSocket Message Type:**
- Protocol definition: `pb/src/client_container.proto`
- Rebuild: `cd pb && ./build`
- Handler: Add to websocket-gateway or message_factory

**New Background Job:**
- Job class: `ruby/lib/jam_ruby/resque/{job_name}.rb`
- Enqueue: Call `Resque.enqueue(JobClass, args)` from models/controllers

## Special Directories

**pb/target/**
- Purpose: Generated Protocol Buffer bindings (Ruby/JavaScript)
- Source: Auto-generated by `pb/build` script from `.proto` files
- Committed: Yes (generated code checked in)

**node_modules/**
- Purpose: npm dependencies for jam-ui
- Source: Installed via `npm install`
- Committed: No (.gitignored)

**vendor/bundle/**
- Purpose: Bundler-installed Ruby gems
- Source: Installed via `bundle install`
- Committed: No (.gitignored)

**.planning/**
- Purpose: GSD project planning files
- Source: Created by /gsd:* commands
- Committed: Yes (project planning state)

---

*Structure analysis: 2026-01-11*
*Update when directory structure changes*
