supadb

The database of supaboards.com

Overview

This is a data repository for managing VTuber, AVTuber information using JSON-based structured data. The repository contains metadata and member information for various VTuber, AVTuber groups, which can be synced to a Supabase database.

Requirements

• Node.js

Setup

npm install

🔒 Environment Variables

Copy .env.sample to create your environment files:

# For development
cp .env.sample .env.local

# For production
cp .env.sample .env.production

Then fill in the following values:

SUPABASE_URL=your_supabase_project_url
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
YOUTUBE_API_KEY=your_youtube_api_key

Usage

Update Metadata

After adding or modifying group data, update the metadata files:

npm run update-metadata

This automatically generates/updates:

• data/jobs.json: List of all job categories
• data/{job_name}/groups.json: List of groups within each job category

Generate Master File

Generate a consolidated file containing all member data:

npm run update-master

This creates:

• data/master.json: Flattened list of all members across all jobs and groups

Useful for bulk operations, data analysis, and external integrations.

Validate Data

npm run validate -- data/{job_name}/{group_name}/members.json

🔒 Sync to Supabase

Automatically syncs all VTuber/AVTuber data to Supabase:

Development:

npm run sync-data:development

Production:

npm run sync-data:production

The sync script:

• Detects all members.json files across all job and group directories
• Creates new threads or updates existing ones
• Handles YouTube channel info, avatars, and tags automatically
• Displays progress per group and overall summary

Contributing

Adding or Updating Data

1. Fork this repository
2. Create or edit JSON files in data/{job_name}/{group_name}/members.json
3. Before committing, run the following commands:

   npm run update-metadata
   npm run update-master

4. Validate your changes: npm run validate -- data/{job_name}/{group_name}/members.json
5. Commit all changes (including generated files)
6. Submit a pull request

Note: CI will automatically verify that metadata files are up-to-date. If you forget to run the update commands, the CI checks will fail and prompt you to run them.

Data Structure

Each members.json follows this schema:

{
  "metadata": {
    "job": "Job Name",
    "group": "Group Name",
    "options": ["Optional tags"],
    "source": "Official website URL"
  },
  "members": [
    {
      "name": "Name",
      "youtube_id": "UC... or @handle",
      "options": ["Optional tags"]
    }
  ]
}

YouTube Channel Handling:

• Members with youtube_id: Will be synced to Supabase with channel info and avatar
• Members with empty youtube_id (""): Will be skipped during sync (no YouTube channel exists or not yet discovered)

YouTube ID Formats

• Channel ID: UCxxxxxxxxxxxxxxxxxxx (22 characters after UC)
• Handle: @username

Validation Rules

• youtube_id must match: ^(UC[a-zA-Z0-9_-]{22}|@[a-zA-Z0-9_-]+)?$ (can be empty string)
• Required fields: metadata.job, metadata.group, member.name, member.youtube_id
• Optional fields: metadata.options, metadata.source, member.options

Data Structure

data/
├── schema.json                              # JSON Schema definition
├── members.template.jsonc                   # Template for new groups
├── jobs.json                                # Auto-generated list of job categories
├── master.json                              # Auto-generated consolidated member list
├── {job_name}/
│   ├── groups.json                          # Auto-generated list of groups
│   └── {group_name}/
│       └── members.json                     # VTuber/AVTuber member data

File Descriptions

• data/schema.json: JSON Schema defining the structure for all member data files
• data/members.template.jsonc: Template for creating new group data files
• data/jobs.json: List of job categories (auto-generated by update-metadata)
• data/master.json: Consolidated flat list of all members (auto-generated by update-master)
• data/{job_name}/groups.json: List of groups per job (auto-generated by update-metadata)
• data/{job_name}/{group_name}/members.json: Per-group member data files

Contributors

dotkarenas

nasufuu

yasainet