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)