Audiometa Frontend

Next.js frontend for audio metadata editing and management.

Table of Contents

• Tech Stack
• Project Structure
• Getting Started
• Scripts
• CI
• Documentation
• License

Tech Stack

• Framework: Next.js (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• Testing: Vitest, Testing Library
• CI: GitHub Actions

Project Structure

.
├── src/
│   ├── app/           # Next.js App Router pages and layouts
│   ├── components/    # React components (features/, ui/)
│   ├── contexts/      # React Context providers
│   ├── hooks/         # Custom hooks
│   ├── lib/           # Utilities and helpers
│   ├── models/        # Types and interfaces
│   └── utils/         # General utilities
├── docs/              # Style guide, testing, versioning
├── .cursor/rules/     # Cursor AI / editor rules
├── .github/
│   ├── workflows/     # CI (validate, branch-protection, publish)
│   └── pull_request_template.md
└── README.md

Getting Started

Prerequisites

• Node.js 20+
• npm (or yarn/pnpm)

Install and run

git clone https://github.com/BehindTheMusicTree/audiometa-frontend.git
cd audiometa-frontend
npm install
cp .env.example .env.local   # if present; set variables as needed
npm run dev

App runs at http://localhost:3001.

Environment variables

Create .env.local from .env.example (when available) and set any required NEXT_PUBLIC_* or API URLs. Do not commit .env.local.

Scripts

Command	Description
npm run dev	Start development server
npm run build	Production build
npm run start	Start production server
npm run lint	Run ESLint
npm run test	Run tests

Add test in package.json if missing (e.g. "test": "vitest run").

CI

• Validate – On push/PR to main and develop: lint, test, build. .github/workflows/validate.yml
• Branch protection – PRs to main must be from hotfix/ or release/; PRs to develop from feature/, chore/, or dependabot/. .github/workflows/branch-protection.yml
• Publish – On tag push v*: checks tag is on main, runs build. .github/workflows/publish.yml. Extend with Docker/deploy when ready.

Documentation

• CHANGELOG.md – Version history and notable changes
• CONTRIBUTING.md – Git Flow, commits, PRs, releasing
• docs/STYLE_GUIDE.md – TypeScript, React, Tailwind, naming
• docs/SEMANTIC_HTML.md – Semantic layout elements
• docs/DATA_ATTRIBUTES.md – data-testid, data-page, etc.
• docs/testing.md – Testing strategy and structure
• docs/VERSIONING.md – Tags and version format
• docs/SEMVER_GUIDE.md – When to bump MAJOR/MINOR/PATCH
• docs/DEPLOYMENT.md – Vercel staging and production setup
• docs/SEO_AND_AEO.md – SEO and AEO strategy and opportunities

The app has a Docs section at /docs that loads documentation from a published bundle (see NEXT_PUBLIC_DOCS_BUNDLE_URL in .env.example). The bundle is produced by the audiometa-python-publish-docs repo.

License

See LICENSE for details.