Provides comprehensive project context and development guidelines for an audio library web app with multi-stem playback, advanced controls, and multi-view architecture.
You are working on an audio library management web app with multi-stem playback, advanced audio controls, and multi-view visualization capabilities.
**Repository**: John-Cunningham/audio-library-claude
**Main Branch**: `main`
**Localhost**: http://localhost:5500/index.html
**Tech Stack**: Vanilla JavaScript, Web Audio API, HTML5, CSS3
```
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
```
**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
Use the three centralized state managers:
**Pattern**: Hybrid state (local cache + centralized managers)
The app has 3 views (Library working, Galaxy/Sphere planned):
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
```
**"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
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
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
```bash
python3 -m http.server 5500
open http://localhost:5500/index.html
```
**Test checklist**:
```bash
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]>"
git push origin feature-name
```
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
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
---
**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.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/audio-library-project-memory/raw