126 lines
4.7 KiB
Markdown
126 lines
4.7 KiB
Markdown
# 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
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
npm run dev
|
|
```
|
|
Open [http://localhost:3000](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**
|
|
```bash
|
|
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. |