Audio Library Project Memory

You are working on an audio library management web app with multi-stem playback, advanced audio controls, and multi-view visualization capabilities.

Project Context

**Repository**: John-Cunningham/audio-library-claude

**Main Branch**: `main`

**Localhost**: http://localhost:5500/index.html

**Tech Stack**: Vanilla JavaScript, Web Audio API, HTML5, CSS3

Core Features

Directory Structure

```

audio-library-claude/

├── index.html # Main HTML entry point

├── CLAUDE.md # Project memory (this context)

├── CHANGELOG.txt # Version history

├── MIGRATION_COMPLETE.md # Latest migration details

│

├── public/ # Public assets

│ ├── lib/ # External libraries

│ ├── media/ # Media files

│ └── icon/ # Icons & favicons

│

├── styles/ # CSS modules

│ ├── main.css

│ ├── playerBar.css

│ ├── stems.css

│ └── views.css

│

├── src/ # Source code (MODULAR!)

│ ├── audio/ # Audio processing

│ ├── components/ # 14 component modules

│ ├── core/ # Core application logic

│ ├── services/ # Service classes

│ ├── state/ # State managers

│ ├── utils/ # Utility functions

│ └── views/ # View renderers

│

├── docs/ # Documentation

│ ├── architecture/ # Architecture analysis

│ ├── refactoring/ # Refactoring progress

│ ├── handoffs/ # Session handoffs

│ └── claude-code-chat-session-logs/

│

└── experiments/ # Experimental/legacy code

```

Critical Architecture Rules

1. MODULAR ARCHITECTURE (V29 Refactoring Complete)

**DO NOT add large functions to app.js!** The codebase was refactored from ~6500 lines → ~1900 lines in app.js.

When adding new functionality:

1. **Create a module** in the appropriate directory:

- `src/components/` → UI components

- `src/state/` → State management

- `src/utils/` → Utility functions

- `src/services/` → Service classes

2. **Use dependency injection** (pass state/callbacks as parameters)

3. **Add thin wrapper in app.js** (3-7 lines maximum)

4. **Expose to window** if needed by HTML

2. State Management Pattern

Use the three centralized state managers:

**Pattern**: Hybrid state (local cache + centralized managers)

3. Multi-View Requirement

The app has 3 views (Library working, Galaxy/Sphere planned):

Instructions for Development

Starting a Session

1. **Check current state**:

```bash

pwd

git branch --show-current

git status

```

2. **Pull latest changes**:

```bash

git pull origin main

```

3. **Create feature branch** (recommended):

```bash

git checkout -b feature-name

```

Finding Information

**"Where is X functionality?"**

1. Check `docs/architecture/APP_JS_AUDIT_2025-10-18.md` - Complete breakdown

2. Search `src/` for the module name

3. Check `app.js` for window exposures

**"How does X work?"**

1. Check relevant state manager (`src/state/`)

2. Check component module (`src/components/`)

3. Read associated docs in `docs/refactoring/`

**"What changed recently?"**

1. Check `CHANGELOG.txt` for version history

2. Check `git log --oneline` for recent commits

3. Check `docs/refactoring/` for refactoring details

Adding a New Feature

1. Create module in appropriate `src/` subdirectory

2. Follow existing patterns (dependency injection, state managers)

3. Create thin wrapper in `app.js` (3-7 lines)

4. Expose to `window` if HTML needs access

5. Update CLAUDE.md with feature description

6. Add entry to CHANGELOG.txt

7. Test thoroughly in browser

Fixing a Bug

1. Identify which module contains the bug (NOT app.js!)

2. Fix in the module itself

3. Test thoroughly at http://localhost:5500/index.html

4. Commit with descriptive message

5. Update CHANGELOG.txt if user-facing

Testing

```bash

Start local server (required for CORS)

python3 -m http.server 5500

Test in browser

open http://localhost:5500/index.html

```

**Test checklist**:

Committing Changes

```bash

Commit frequently with clear messages

git add .

git commit -m "feat: Add feature description

Detailed explanation if needed.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>"

Push to GitHub

git push origin feature-name

```

Key Documentation Files

Architecture Understanding

Refactoring Context

Session Continuity

Common Pitfalls to Avoid

1. **Adding logic to app.js** → Extract to modules instead

2. **Direct state mutation** → Use state managers

3. **Global variables** → Use state managers

4. **Monolithic functions** → Break into smaller modules

5. **Skipping documentation** → Update CLAUDE.md and CHANGELOG.txt

6. **Not testing** → Always test in browser before committing

Current Status

Working Features ✅

In Progress 🚧

Known Issues 🐛

Key Concepts to Remember

1. **Hybrid State**: Local variables + centralized state managers

2. **Dependency Injection**: Modules receive dependencies as parameters

3. **Thin Wrappers**: app.js coordinates, doesn't implement business logic

4. **Multi-View Architecture**: State persists across view switches

5. **Component Modules**: Reusable, testable, isolated units

Getting Help

---

**Remember**: This is a clean, modular codebase after V29 refactoring. Keep it that way! When adding functionality, always create a new module rather than extending app.js.