seth
/
jam-cloud
mirror of https://bitbucket.org/jamkazam/jam-cloud.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity
jam-cloud/.planning/codebase/STRUCTURE.md

7.8 KiB
Raw Permalink Blame History

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