Skip to content

Database and Storage Data Models and Collections

Jump to bottom
github-actions[bot] edited this page May 2, 2026 · 4 revisions

Data Models and Collections

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Collections and Schemas
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document provides comprehensive data model documentation for the ChordMiniApp collections and schemas stored in Firestore. It covers the main collections including transcriptions, translations, lyrics, key detections, segmentation jobs, and melody caches. For each collection, we define document structure, field types, validation rules, and relationships. We explain indexing strategy, query optimization, caching policies, migration procedures, and administrative maintenance via the Firestore Admin SDK. Finally, we outline TypeScript interfaces and type safety measures, and address data lifecycle management including retention, archival, and deletion strategies.

Project Structure

The data model spans several layers:

  • Frontend services that read/write Firestore documents and manage caches
  • Backend APIs that expose endpoints for melody cache and segmentation jobs
  • Firestore configuration for indexes and security rules
  • Administrative scripts for bulk operations and backfills
graph TB
subgraph "Frontend"
FSvc["firestoreService.ts"]
SCache["sheetSageCacheClient.ts"]
end
subgraph "Backend"
API["melody-cache route.ts"]
SegSvc["segmentationJobService.ts"]
end
subgraph "Firestore"
Rules["firestore.rules"]
Idx["firestore.indexes.json"]
Trans["transcriptions"]
Melody["melody"]
Jobs["segmentationJobs"]
Keys["keyDetections"]
Lyrics["lyrics"]
TransCache["transcriptionCache"]
TrCache["translationCache"]
end
subgraph "Admin Tools"
AdminSDK["firestoreAdminService.ts"]
DelCache["delete-cache-admin.js"]
Backfill1["backfill-transcription-homepage-metadata.js"]
Backfill2["backfill-transcription-usage-count.js"]
end
FSvc --> Trans
FSvc --> Melody
FSvc --> Keys
FSvc --> Lyrics
FSvc --> TransCache
FSvc --> TrCache
SCache --> API
API --> Melody
SegSvc --> Jobs
Rules --> Trans
Rules --> Melody
Rules --> Jobs
Rules --> Keys
Rules --> Lyrics
Rules --> TransCache
Rules --> TrCache
Idx --> Trans
AdminSDK --> Trans
AdminSDK --> Melody
AdminSDK --> Jobs
AdminSDK --> Keys
AdminSDK --> Lyrics
DelCache --> Trans
DelCache --> Melody
Backfill1 --> Trans
Backfill2 --> Trans
Loading

Diagram sources

Section sources

Core Collections and Schemas

Transcriptions

Purpose: Store beat and chord analysis results with optional enrichment metadata and search keys for homepage curation.

  • Collection path: transcriptions
  • Document ID: constructed from videoId, beatModel, and chordModel
  • Key fields:
    • videoId: string (YouTube video identifier)
    • beatModel: string (beat detection model name)
    • chordModel: string (chord detection model name)
    • beats: array of beat entries
    • chords: array of chord entries with timing
    • synchronizedChords: array of { chord, beatIndex, beatNum? }
    • createdAt: timestamp
    • audioDuration?: number
    • timeSignature?: number|null
    • bpm?: number|null
    • beatShift?: number
    • keySignature?: string|null
    • keyModulation?: string|null
    • chordCorrections?: map|string[]
    • sequenceCorrections?: structured corrections
    • correctedChords?: string[]
    • originalChords?: string[]
    • romanNumerals?: structured analysis
    • isPrimaryVariant?: boolean
    • displayPriority?: number|null
    • searchableKeys?: string[]
    • usageCount?: number

Validation rules (simplified in rules for stability):

  • Enforce presence of core fields and timestamps
  • Limit total field count
  • Temporary permissive rules during validation isolation

Caching and normalization:

  • Normalization pipeline ensures consistent structure and derived fields
  • Homepage variant scoring and primary variant assignment
  • Increment usageCount atomically

Indexes:

  • Composite index for isPrimaryVariant + createdAt (descending)
  • Composite index for isPrimaryVariant + searchableKeys (contains) + createdAt (descending)

Section sources

Transcription Cache

Purpose: Store precomputed transcription results for quick retrieval.

  • Collection path: transcriptionCache
  • Validation: permissive during stabilization
  • Access: read allowed; create/update allowed; delete restricted

Section sources

Translations

Purpose: Store translated lyrics.

  • Collection path: translations
  • Validation: permissive during stabilization
  • Access: read allowed; create/update allowed; delete restricted to admins

Section sources

Translation Cache

Purpose: Store cached translation results.

  • Collection path: translationCache
  • Validation: permissive during stabilization
  • Access: read allowed; create/update allowed; delete restricted to admins

Section sources

Lyrics

Purpose: Store transcribed lyrics (from Music.AI).

  • Collection path: lyrics
  • Validation: permissive during stabilization
  • Access: read allowed; create/update allowed; delete restricted to admins

Section sources

Key Detections

Purpose: Store musical key analysis results.

  • Collection path: keyDetections
  • Validation: permissive during stabilization
  • Access: read allowed; create/update allowed; delete restricted to admins

Section sources

Melody Cache

Purpose: Store Sheet Sage melody transcription results.

  • Collection path: melody
  • Document ID: videoId
  • Fields:
    • videoId: string
    • model: string (fixed model identifier)
    • noteEvents: array of { onset, offset, pitch, velocity }
    • noteEventCount: number
    • beatTimes: number[]
    • beatsPerMeasure: number
    • tempoBpm: number
    • createdAt: timestamp
  • Normalization:
    • Filters invalid note events
    • Sorts and clamps note attributes
    • Validates numeric fields

Frontend cache:

  • SmartFirebaseCache wrapper for memoization and normalization

Backend API:

  • GET endpoint serves cached melody data for a given videoId

Section sources

Segmentation Jobs

Purpose: Track asynchronous SongFormer segmentation jobs with state and result persistence.

  • Collection path: segmentationJobs
  • Fields include job identifiers, status, timestamps, hashes, and result metadata
  • Operations:
    • Create/update job documents
    • Find active/completed jobs by request hash
    • Cleanup stale jobs
    • Delete non-completed jobs by request hash

TTL and cleanup:

  • Stale job detection based on status and updatedAtMs
  • Cron-triggered cleanup endpoint

Section sources

Architecture Overview

sequenceDiagram
participant Client as "Client App"
participant FS as "firestoreService.ts"
participant Cache as "SmartFirebaseCache"
participant FB as "Firestore"
participant API as "melody-cache route.ts"
Client->>FS : getMelodyTranscription(videoId)
FS->>Cache : peek(videoId)
alt cache hit
Cache-->>FS : normalized melody data
FS-->>Client : melody data
else cache miss
FS->>FB : getDoc(melody, videoId)
FB-->>FS : raw melody data
FS->>FS : normalizeMelodyTranscriptionData()
FS->>Cache : set(videoId, data)
FS-->>Client : melody data
end
Client->>API : GET /api/melody-cache?videoId=...
API->>FS : getMelodyTranscription(videoId)
FS-->>API : melody data
API-->>Client : JSON response
Loading

Diagram sources

Detailed Component Analysis

Transcription Data Model and Normalization

The transcription schema supports beat/chord synchronization, key analysis, and enrichment metadata. Normalization ensures:

  • Consistent chord timing (time vs start)
  • Rebuilt synchronized chords when beats/chords change
  • Derived fields (keySignature, keyModulation, chordCorrections)
  • Sequence corrections and roman numeral analysis
  • Homepage variant scoring and primary variant flagging
flowchart TD
Start(["Normalize Transcription"]) --> CheckSeq["Has sequenceCorrections?"]
CheckSeq --> |Yes| UseSC["Use provided sequenceCorrections"]
CheckSeq --> |No| BuildSC["Build legacy corrections from chordCorrections/originalChords"]
BuildSC --> HasAny{"Any correction applied?"}
HasAny --> |No| NullSC["Set sequenceCorrections=null"]
HasAny --> |Yes| UseSC
UseSC --> Merge["Merge with existing fields"]
NullSC --> Merge
Merge --> Timing["Normalize chord timing fields"]
Timing --> Sync["Rebuild synchronizedChords if needed"]
Sync --> Derived["Derive keySignature, keyModulation, chordCorrections"]
Derived --> Output(["Normalized Transcription"])
Loading

Diagram sources

Section sources

Melody Transcription Data Model and Normalization

Melody documents are normalized to ensure:

  • Valid note event ranges and sorted order
  • Clamped MIDI pitch/velocity bounds
  • Beat times filtered to finite numbers
  • Derived counts and defaults for beatsPerMeasure/tempoBpm
flowchart TD
MStart(["Normalize Melody"]) --> FilterNE["Filter valid noteEvents"]
FilterNE --> SortNE["Sort by onset/pitch/offset"]
SortNE --> Clamp["Clamp pitch 0..127<br/>velocity 0..127"]
Clamp --> FilterBT["Filter valid beatTimes"]
FilterBT --> Defaults["Apply defaults:<br/>beatsPerMeasure=4<br/>tempoBpm=120"]
Defaults --> MOut(["Normalized Melody"])
Loading

Diagram sources

Section sources

Segmentation Job Lifecycle

Segmentation jobs are tracked with status transitions and TTL semantics. The service:

  • Creates/updates job documents with timestamps and hashes
  • Finds active/completed jobs by request hash
  • Detects stale jobs and deletes them
  • Cleans up non-completed jobs for the same request hash
sequenceDiagram
participant Client as "Client"
participant API as "Segmentation API"
participant Svc as "segmentationJobService.ts"
participant FB as "Firestore"
Client->>API : GET /jobs/[jobId]
API->>Svc : getSegmentationJob(jobId)
Svc->>FB : getDoc(segmentationJobs, jobId)
FB-->>Svc : job snapshot
Svc-->>API : job data
API-->>Client : status/progress/error
Client->>API : PATCH /jobs/[jobId] { status : "completed" }
API->>Svc : updateSegmentationJob(jobId, updates)
Svc->>FB : setDoc(..., { merge : true })
Svc->>FB : deleteNonCompletedSegmentationJobsByRequestHash(...)
FB-->>Svc : ack
Svc-->>API : ok
API-->>Client : success
Loading

Diagram sources

Section sources

Indexing Strategy and Query Optimization

Composite indexes enable efficient queries:

  • Primary variant selection and chronological ordering
  • Filtering by searchable keys for homepage curation
erDiagram
TRANSCRIPTIONS {
string videoId
string beatModel
string chordModel
boolean isPrimaryVariant
string[] searchableKeys
timestamp createdAt
number usageCount
}
Loading

Diagram sources

Section sources

Caching Policies

  • Transcriptions: SmartFirebaseCache with normalization and eviction
  • Melody: SmartFirebaseCache with normalization and memoization
  • Homepage variant metadata: batched updates to all variants for a videoId
  • Usage count: atomic increment via server-side increment

Section sources

Data Migration Procedures

  • Schema versioning: introduce new fields alongside existing ones; keep backward compatibility
  • Backfill scripts:
    • Homepage metadata backfill: compute isPrimaryVariant, displayPriority, searchableKeys
    • Usage count backfill: increment usageCount for existing transcriptions
  • Admin SDK:
    • Bulk delete documents by IDs
    • Retrieve/set documents programmatically

Section sources

Firestore Admin SDK Usage

  • Authentication: Google Auth with service account or ADC
  • Operations:
    • Batch delete documents
    • Get/set documents with typed encoding/decoding
  • Batch size: 500 writes per commit

Section sources

TypeScript Interfaces and Type Safety

  • Audio analysis types: beat/chord detection results and analysis result shapes
  • Music.AI types: lyrics, lines, markers, and job/result structures
  • Sheet Sage types: melody note events and result metadata

These interfaces ensure type-safe handling of backend responses and internal data structures.

Section sources

Data Lifecycle Management

  • Retention: no explicit TTL fields; rely on administrative cleanup and usage-based pruning
  • Archival: not implemented; consider exporting via Admin SDK for long-term storage
  • Deletion:
    • Admin-only delete for translations, lyrics, keyDetections, transcriptions, transcriptionCache, translationCache
    • Segmentation jobs cleaned up by staleness
    • Bulk deletion via Admin SDK

Section sources

Dependency Analysis

graph LR
FS["firestoreService.ts"] --> TR["transcriptions"]
FS --> ML["melody"]
FS --> KEYS["keyDetections"]
FS --> LYR["lyrics"]
FS --> TC["transcriptionCache"]
FS --> TRL["translationCache"]
API["melody-cache route.ts"] --> FS
SC["sheetSageCacheClient.ts"] --> API
SEG["segmentationJobService.ts"] --> SJ["segmentationJobs"]
ADM["firestoreAdminService.ts"] --> TR
ADM --> ML
ADM --> SJ
ADM --> KEYS
ADM --> LYR
IDX["firestore.indexes.json"] --> TR
RULE["firestore.rules"] --> TR
RULE --> ML
RULE --> SJ
RULE --> KEYS
RULE --> LYR
RULE --> TC
RULE --> TRL
Loading

Diagram sources

Section sources

Performance Considerations

  • Composite indexes:
    • Enable efficient filtering by isPrimaryVariant and sorting by createdAt
    • Support array-contains queries on searchableKeys for homepage curation
  • Caching:
    • SmartFirebaseCache reduces read latency and minimizes network requests
    • Normalization avoids repeated computation
  • Batch operations:
    • Firestore Admin SDK batches deletions to reduce cost and latency
  • Atomic increments:
    • usageCount via server-side increment prevents race conditions
  • CORS resilience:
    • Session-wide Firestore disable on CORS/network errors prevents repeated failures

[No sources needed since this section provides general guidance]

Troubleshooting Guide

  • CORS/network errors:
    • Firestore operations may temporarily disable Firestore for the session
    • Check browser console for CORS-related messages
  • Validation errors:
    • Rules temporarily relaxed to isolate permission issues
    • Review field types and sizes; ensure createdAt is a valid timestamp
  • Admin operations:
    • Verify service account credentials and project ID environment variables
    • Confirm batch sizes and error messages from Admin SDK commits
  • Segmentation jobs:
    • Use cleanup endpoints to remove stale jobs
    • Verify request hash uniqueness and status transitions

Section sources

Conclusion

The ChordMiniApp data model centers on robust schemas for transcriptions and melody results, supported by strong caching, composite indexes, and administrative tooling. Validation rules are intentionally permissive during stabilization, while type-safe TypeScript interfaces ensure correctness across the stack. The indexing strategy optimizes common queries, and the Admin SDK enables scalable maintenance tasks. Together, these components deliver a reliable foundation for analysis results, lyrics, and segmentation workflows.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Field Definitions and Types (Selected)

  • TranscriptionData

    • videoId: string
    • beatModel: string
    • chordModel: string
    • beats: BeatInfo[]
    • chords: ChordDetectionResult[]
    • synchronizedChords: { chord: string; beatIndex: number; beatNum?: number }[]
    • createdAt: timestamp
    • audioDuration?: number
    • timeSignature?: number|null
    • bpm?: number|null
    • beatShift?: number
    • keySignature?: string|null
    • keyModulation?: string|null
    • chordCorrections?: map|string[]
    • sequenceCorrections?: structured
    • correctedChords?: string[]
    • originalChords?: string[]
    • romanNumerals?: structured
    • isPrimaryVariant?: boolean
    • displayPriority?: number|null
    • searchableKeys?: string[]
    • usageCount?: number

  • MelodyTranscriptionData

    • videoId: string
    • model: string
    • noteEvents: { onset: number; offset: number; pitch: number; velocity: number }[]
    • noteEventCount: number
    • beatTimes: number[]
    • beatsPerMeasure: number
    • tempoBpm: number
    • createdAt: timestamp

Section sources

ChordMiniApp Wiki

General

API Reference

Architecture and Design

Audio Processing and Analysis

Backend Services

Database and Storage

Deployment and Operations

Experimental Features

Frontend Application

Lyrics and Text Processing

Machine Learning Models

Project Overview

Visualization and User Interface

Clone this wiki locally