# MetaMuLate Decomposition

> Modular React TypeScript port of the MetaMuLate Primary Data Reconciliation Tool for Orchard Suite OA Applications

## Overview

This package contains the decomposed, modular React TypeScript implementation of MetaMuLate, extracted from the original monolithic HTML file (`metamulate_decompose.html`) and refactored for integration with `orchard-suite-oa-applications`.

## Features

- 🍎 **Apple Music / iTunes** - Search with ISRC detection and artist discovery
- 🎵 **MusicBrainz** - Recording lookup with multi-strategy search
- 💿 **Discogs** - Authenticated release parsing with credits
- 📝 **Genius** - Lyrics and songwriter credits extraction
- 📚 **Wikidata** - SPARQL entity queries for linked data
- 🎸 **Bandcamp** - HTML scraping with multiple extraction strategies
- 🌐 **Web Scrape** - Generic ContentAnalyzer for any URL
- ❄️ **Snowflake** - Internal database integration via GraphQL
- ⭐ **Authority Score** - Weighted scoring with vintage/completeness bonuses
- 📊 **Metadata Matrix** - GridTable-based comparison view
- 🏆 **Golden Record** - Inline editing with source provenance tracking

## Project Structure

```text
MetaMulate Decomposition/
├── metamulate_decompose.html     # Original source file (reference)
├── docs/                         # Documentation
│   ├── component-mapping.md      # HTML → React component mapping
│   ├── graphql-schema.md         # GraphQL schema definition
│   ├── IMPLEMENTATION_GUIDE.md   # Integration guide
│   ├── COMPROMISES.md            # Trade-offs and decisions
│   ├── THEME_MIGRATION.md        # Theme system guide
│   └── TESTING_STRATEGY.md       # Testing approach
└── proposed-module/              # React TypeScript implementation
    ├── src/
    │   ├── components/           # React components (78 files)
    │   │   ├── metamulateOAPanel/  # Main panel container
    │   │   ├── artistSearch/       # Search input
    │   │   ├── trackList/          # Track listing
    │   │   ├── metadataMatrix/     # GridTable matrix
    │   │   ├── goldenRecord/       # Right panel
    │   │   ├── consolePanel/       # Debug console
    │   │   └── modals/             # Connections, WebScrape
    │   ├── contexts/             # React contexts
    │   ├── hooks/                # Custom hooks
    │   ├── services/             # Business logic
    │   │   └── scrapers/           # 7 API scrapers
    │   ├── types/                # TypeScript interfaces
    │   ├── utils/                # Utility functions
    │   ├── data/                 # GraphQL queries, SQL templates
    │   ├── config/               # Configuration hooks
    │   └── styles/               # Orchard Light Theme (SCSS)
    ├── shared/                   # Shared components
    │   └── components/oaPanel/   # OA panel wrapper
    ├── package.json
    ├── tsconfig.json
    ├── vite.config.ts
    └── jest.config.js
```

## Quick Start

```bash
cd proposed-module
npm install
npm run dev
```

## Available Scripts

```bash
npm run dev          # Start Vite dev server
npm run build        # Production build
npm test             # Run Jest tests
npm run test:watch   # Watch mode
npm run typecheck    # TypeScript check
npm run lint         # ESLint
npm run codegen      # Generate GraphQL types
```

## Key Features

### ✅ Completed

- **TypeScript Types** - Full definitions for TrackMetadata, GoldenRecord, DataValue, SourceRegistry
- **Core Services** - Logger, ProxyService, RateLimiter, ScrapeManager, ApiClient
- **API Scrapers** - Apple, MusicBrainz, Discogs, Genius, Wikidata, Bandcamp, WebScrape
- **React Components** - MetamulateOAPanel, ArtistSearch, TrackList, MetadataMatrix, GoldenRecordPanel, ConsolePanel
- **Modals** - ConnectionsModal (API tokens), WebScrapeModal (URL/content analysis)
- **Custom Hooks** - useGoldenRecord, useScraping, useLocalStorage
- **Field Registry** - 30+ metadata fields with categories and validation
- **Authority Score** - ISRC, vintage, P-Line, label, MusicBrainz bonuses
- **Orchard Light Theme** - Full OA token mapping in SCSS
- **Unit Tests** - Authority score, helpers, component tests
- **Documentation** - Component mapping, GraphQL schema, implementation guides

### ⏳ Pending Backend

- GraphQL codegen integration (waiting for backend schema deployment)
- Snowflake query hook completion
- Feature flag integration

### 📋 Future Enhancements

- E2E tests with Cypress
- Visual regression tests
- Batch export functionality
- Keyboard navigation shortcuts

## Architecture Decisions

| Decision | Rationale |
|----------|-----------|
| React 18 + TypeScript | Type safety, hooks, concurrent features |
| Vite | Fast HMR, modern ESM bundling |
| useReducer + Context | Simpler than Redux, fits component tree |
| Orchard Light Theme | OA token mapping via CSS custom properties |
| Service singletons | Direct port of original business logic |
| GridTable (suite-components) | Flexible cell rendering for matrix |
| Collapsible categories | Manage information density |

## Component Hierarchy

```text
MetamulateOAPanelContainer
└── MetamulateOAPanel
    ├── ArtistSearch
    ├── TrackList
    │   └── TrackListItem[]
    ├── MetadataMatrix
    │   └── MatrixCell[]
    ├── GoldenRecordPanel
    ├── ConsolePanel (debug mode)
    ├── ConnectionsModal
    └── WebScrapeModal
```

## Documentation

- [Implementation Guide](docs/IMPLEMENTATION_GUIDE.md) - Step-by-step integration instructions
- [Component Mapping](docs/component-mapping.md) - HTML sections → React components
- [GraphQL Schema](docs/graphql-schema.md) - Backend API definitions
- [Compromises](docs/COMPROMISES.md) - Trade-offs and decisions explained
- [Theme Migration](docs/THEME_MIGRATION.md) - Suite theme integration
- [Testing Strategy](docs/TESTING_STRATEGY.md) - Test approach and examples

## Environment Variables

```env
VITE_APPLE_MUSIC_API_KEY=your_key
VITE_DISCOGS_TOKEN=your_token
VITE_GENIUS_TOKEN=your_token
```

## Contributing

1. Read the [Implementation Guide](docs/IMPLEMENTATION_GUIDE.md)
2. Check existing issues/TODOs in code
3. Follow TypeScript strict mode
4. Write tests for new features
5. Update documentation as needed

## License

Internal use only - The Orchard