BA_TTS_Annotation_Plattform/README.md

TTS Dialect Annotation Platform

A Next.js web application for annotating and managing dialect audio datasets.

Prerequisites

• Node.js 18+
• npm or yarn

Quick Start

1. Install Dependencies

npm install

2. Set Up Environment Variables

Create a .env file in the project root with necessary configuration based on .env.example.

3. Initialize Database

npm run db:generate  # Generate migration files (if changes were made to the db)
npm run db:push     # Apply migrations to database

4. Run Development Server

npm run dev

Open http://localhost:3000 in your browser.

Project Structure

• src/app/ - Next.js pages and API routes
  • admin/ - Admin dashboard pages
  • annotate/ - Annotation pages (actual application)
  • user/ - User authentication pages
  • api/ - Different API-Pages for usage in frontend (Download, Upload, User)
  • actions/ - Server actions for data operations
• src/components/ - Reusable React components
• src/lib/ - Utilities, database, and auth configuration
• drizzle/ - Database migration files

Available Scripts

Command	Description
npm run dev	Start development server (localhost:3000)
npm run build	Build for production
npm run start	Start production server
npm run db:generate	Generate database migrations
npm run db:push	Push migrations to database

Tech Stack

• Framework: Next.js 16
• Auth: Better-Auth
• Database: Drizzle ORM + SQLite
• Styling: Tailwind CSS
• Language: TypeScript

Modifying the Data Model

Steps to Update the Database Schema

1. Edit the Schema

   • Open src/lib/model/ and modify the relevant schema files
   • Export any new tables in src/lib/model/index.ts

2. Generate Migration

   npm run db:generate
   

   This creates SQL migration files in the drizzle/ directory.

3. Review the Migration

   • Check the generated SQL file in drizzle/ to ensure correctness
   • Make manual adjustments if needed

4. Update Server Actions (if needed)

   • Update or create server actions in src/app/actions/ to handle the new fields/tables

Example: Adding a New Field

1. Open src/lib/model/dataset_entry.ts
2. Add the new column to the schema
3. Run npm run db:generate
4. Review and run npm run db:push
5. Update relevant server actions and components

Admin Signup System

The platform automatically generates a one-time admin token on startup if no admin exists in the database. This token is logged to the console and can only be used once.

Upgrading to Admin Account

1. Sign in with your regular account
2. Try to access /admin
3. You'll see a form asking for the admin token
4. Paste the token from the console output
5. Click "Admin aktivieren" to upgrade your account

After successful upgrade:

• The token becomes invalid
• Your account gains full admin privileges
• No new token is generated (admin now exists)
• Trying to upgrade another account will fail (token is spent)

Data Model

The application schema is defined with Drizzle ORM under src/lib/model/. Below are short descriptions of the available schema files and what they represent; see the files themselves for full structure.

• auth-schema.ts — user and authentication-related tables: user (accounts and admin flag), session (auth sessions), account (external OAuth/accounts), and verification (verification tokens).
• dataset.ts — dataset table: logical collections of audio items and dataset-level metadata.
• dataset_entry.ts — dataset_entry table: individual audio metadata rows belonging to a dataset (file path, speaker id, dialect labels, metrics, etc.).
• experiment.ts — experiment table: admin-configured annotation experiments referencing a dataset and experiment settings.
• experiment_calibration.ts — experiment_calibration table: ordered calibration items (audio + labels) used when calibrationEnabled is set on an experiment.
• annotation.ts — annotation table: annotator responses for dataset entries within experiments (rating, confidence, chosen dialect label); includes a uniqueness constraint to avoid duplicate annotations per user/item/experiment.
• participant.ts — participant table: links users to experiments and stores onboarding/calibration answers per participant.

When you change the model files in src/lib/model/, run the migration steps in "Modifying the Data Model" to generate and push migrations.

Logical Steps: Creating and publishing an experiment

1. Create a new dataset containing all Samples. Can also be created by duplicating an already present dataset.
2. Create a new experiment using a dataset.
3. Publish the experiment.