feat(song): add song lyrics CRUD endpoints

AGENTS.md

@@ -11,6 +11,10 @@
 - `apps/frontend`: Web interface (Not yet implemented)
 - `packages/db`: Prisma schema and generated database client
 - `packages/core`: Shared business logic, DTOs, and Zod schemas
+- `packages/embedding`: A standalone embedding REST service
+- `packages/logger`: The application logger setup
+- `packages/observability`: Observability configurations
+- `packages/env`: Package for managing environment variables
 
 ## 2. Core Mental Model & Architecture
 
@@ -68,17 +72,10 @@ These rules are absolute. Violation will cause pipeline or runtime failures.
 - **camelCase**: Functions (`getUserById`), Variables, and standard file names (`authHandler.ts`).
 - **UPPER_SNAKE_CASE**: Constants (`MAX_RATE_LIMIT`).
 
-### Import Hierarchy
-Order imports from farthest to closest. Prioritize path aliases
-1. External: Built-in and external NPM packages.
-2. Workspace: Internal packages (`@cvsa/core`, `@cvsa/db`).
-3. Aliases: `@/*`, `@modules/*`, `@common/*` pointing to `./src/`.
-4. **[PROHIBITED]**: relative paths (`../`, `./`, `../../../`, etc.)
-
 ### Module-Specific Information
 - **Backend**:
 	1. Our endpoints starts with `/v2` and this prefix is already configured in root handler. In all of the rest handlers, always use the complete path **without** the version prefix (e.g. `/song/:id/details`)
-	2. **[PROHIBITED]**: DO NOT use verbs in paths. Endpoints should strictly follows the RESTful style.
+	2. **[PROHIBITED]**: DO NOT use verbs in paths. Endpoints should strictly follows the RESTful pattern.
 
 ## 5. Execution Commands & Testing
 

apps/backend/bunfig.toml

@@ -10,4 +10,6 @@ coveragePathIgnorePatterns = [
   "src/utils/randomId.ts",
   "src/types/**",
   "**/observability/src/**",
+  "**/packages/core/**",
+  "src/*.ts"
 ]

apps/backend/package.json

@@ -6,8 +6,8 @@
 		"lint": "bunx --bun biome lint",
 		"dev": "NODE_ENV=development bun --watch src/index.ts",
 		"start": "bun src/index.ts",
-		"test": "NODE_ENV=test bun test",
-		"test:coverage": "NODE_ENV=test bun test --coverage",
+		"test": "bun test --concurrent",
+		"test:coverage": "bun test --coverage --concurrent",
 		"typecheck": "bunx --bun tsc --noEmit"
 	},
 	"devDependencies": {

apps/backend/src/common/error/index.ts

@@ -1,3 +1,2 @@
-export * from "./ConflictError";
 export * from "./RateLimitError";
 export * from "./getErrorResponse";

apps/backend/src/errorHandler.ts

@@ -8,19 +8,13 @@ import { i18nMiddleware } from "@/middlewares";
 import { ip } from "elysia-ip";
 import { formatGinLog, getLogLevelForRequest } from "@common/log";
 
-const AUTH_CONFLICT_CODES = [
-	"USERNAME_IS_ALREADY_TAKEN",
-	"USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL",
-] as const;
-
 const AUTH_INVALID_CODES = [
 	"INVALID_CREDENTIALS",
 	"INVALID_EMAIL_OR_PASSWORD",
 	"USER_NOT_FOUND",
 	"EMAIL_NOT_VERIFIED",
 ] as const;
 
-type AuthConflictCode = (typeof AUTH_CONFLICT_CODES)[number];
 type AuthInvalidCode = (typeof AUTH_INVALID_CODES)[number];
 
 interface ErrorStoreData {

apps/backend/src/handlers/catalog/song/create.ts

@@ -1,7 +1,11 @@
 import { Elysia } from "elysia";
-import { CreateSongRequestSchema, ErrorResponseSchema, songService } from "@cvsa/core";
+import {
+	CreateSongRequestSchema,
+	ErrorResponseSchema,
+	SongResponseSchema,
+	songService,
+} from "@cvsa/core";
 import { authMiddleware } from "@/middlewares";
-import { SongSchema } from "@cvsa/db";
 import { traceTask } from "@/common/trace";
 
 export const songCreateHandler = new Elysia({ name: "songCreateHandler" }).use(authMiddleware).post(
@@ -19,7 +23,7 @@ export const songCreateHandler = new Elysia({ name: "songCreateHandler" }).use(a
 			description: "Create a new song entry in the catalog. Requires authentication.",
 		},
 		response: {
-			201: SongSchema,
+			201: SongResponseSchema,
 			401: ErrorResponseSchema,
 		},
 	}

apps/backend/src/handlers/catalog/song/index.ts

@@ -4,10 +4,12 @@ import { songUpdateHandler } from "./update";
 import { songDeleteHandler } from "./delete";
 import { songDetailsHandler } from "./details";
 import { songSearchHandler } from "./search";
+import { songLyricsHandler } from "./lyrics";
 
 export const songHandler = new Elysia({ name: "songHandler" })
 	.use(songDetailsHandler)
 	.use(songCreateHandler)
 	.use(songUpdateHandler)
 	.use(songDeleteHandler)
-	.use(songSearchHandler);
+	.use(songSearchHandler)
+	.use(songLyricsHandler);

apps/backend/src/handlers/catalog/song/lyrics/create.ts

@@ -0,0 +1,38 @@
+import { Elysia } from "elysia";
+import {
+	ErrorResponseSchema,
+	SongLyricsCreateRequestSchema,
+	SongLyricsResponseSchema,
+	songService,
+} from "@cvsa/core";
+import { authMiddleware } from "@/middlewares";
+import { traceTask } from "@/common/trace";
+import z from "zod";
+
+export const songLyricsCreateHandler = new Elysia({ name: "songLyricsCreateHandler" })
+	.use(authMiddleware)
+	.post(
+		"/song/:id/lyric",
+		async ({ body, params, status }) => {
+			const lyric = await traceTask("songService.createLyric", async () => {
+				return await songService.createLyric(params.id, body);
+			});
+			return status(201, lyric);
+		},
+		{
+			body: SongLyricsCreateRequestSchema,
+			detail: {
+				summary: "Create Song Lyric",
+				description: "Add a new lyrics item for a song. Requires authentication.",
+			},
+			response: {
+				201: SongLyricsResponseSchema,
+				400: ErrorResponseSchema,
+				401: ErrorResponseSchema,
+				404: ErrorResponseSchema,
+			},
+			params: z.object({
+				id: z.coerce.number().int().positive(),
+			}),
+		}
+	);

apps/backend/src/handlers/catalog/song/lyrics/delete.ts

@@ -0,0 +1,34 @@
+import { Elysia } from "elysia";
+import { ErrorResponseSchema, songService } from "@cvsa/core";
+import { authMiddleware } from "@/middlewares";
+import { traceTask } from "@/common/trace";
+import z from "zod";
+
+export const songLyricsDeleteHandler = new Elysia({ name: "songLyricsDeleteHandler" })
+	.use(authMiddleware)
+	.delete(
+		"/song/:id/lyric/:lyricId",
+		async ({ params, set }) => {
+			await traceTask("songService.deleteLyric", async () => {
+				return await songService.deleteLyric(params.id, params.lyricId);
+			});
+			set.status = 204;
+			return null;
+		},
+		{
+			detail: {
+				summary: "Delete Song Lyric",
+				description: "Delete a specific lyrics item for a song. Requires authentication.",
+			},
+			response: {
+				204: z.null(),
+				400: ErrorResponseSchema,
+				401: ErrorResponseSchema,
+				404: ErrorResponseSchema,
+			},
+			params: z.object({
+				id: z.coerce.number().int().positive(),
+				lyricId: z.coerce.number().int().positive(),
+			}),
+		}
+	);

apps/backend/src/handlers/catalog/song/lyrics/get.ts

@@ -0,0 +1,29 @@
+import { Elysia } from "elysia";
+import { ErrorResponseSchema, SongLyricsResponseSchema, songService } from "@cvsa/core";
+import z from "zod";
+import { traceTask } from "@/common/trace";
+
+export const songLyricsGetHandler = new Elysia().get(
+	"/song/:id/lyric/:lyricId",
+	async ({ params, status }) => {
+		const lyric = await traceTask("songService.getLyric", async () => {
+			return await songService.getLyric(params.id, params.lyricId);
+		});
+		return status(200, lyric);
+	},
+	{
+		detail: {
+			summary: "Get Song Lyric",
+			description: "Retrieve a specific lyrics item for a song by its ID.",
+		},
+		response: {
+			200: SongLyricsResponseSchema,
+			400: ErrorResponseSchema,
+			404: ErrorResponseSchema,
+		},
+		params: z.object({
+			id: z.coerce.number().int().positive(),
+			lyricId: z.coerce.number().int().positive(),
+		}),
+	}
+);

apps/backend/src/handlers/catalog/song/lyrics/index.ts

@@ -0,0 +1,13 @@
+import { Elysia } from "elysia";
+import { songLyricsListHandler } from "./list";
+import { songLyricsGetHandler } from "./get";
+import { songLyricsCreateHandler } from "./create";
+import { songLyricsUpdateHandler } from "./update";
+import { songLyricsDeleteHandler } from "./delete";
+
+export const songLyricsHandler = new Elysia({ name: "songLyricsHandler" })
+	.use(songLyricsListHandler)
+	.use(songLyricsGetHandler)
+	.use(songLyricsCreateHandler)
+	.use(songLyricsUpdateHandler)
+	.use(songLyricsDeleteHandler);

apps/backend/src/handlers/catalog/song/lyrics/list.ts

@@ -0,0 +1,28 @@
+import { Elysia } from "elysia";
+import { ErrorResponseSchema, SongLyricsListResponseSchema, songService } from "@cvsa/core";
+import z from "zod";
+import { traceTask } from "@/common/trace";
+
+export const songLyricsListHandler = new Elysia().get(
+	"/song/:id/lyrics",
+	async ({ params, status }) => {
+		const lyrics = await traceTask("songService.listLyrics", async () => {
+			return await songService.listLyrics(params.id);
+		});
+		return status(200, lyrics);
+	},
+	{
+		detail: {
+			summary: "List Song Lyrics",
+			description: "Retrieve all available lyrics for a specific song by its ID.",
+		},
+		response: {
+			200: SongLyricsListResponseSchema,
+			400: ErrorResponseSchema,
+			404: ErrorResponseSchema,
+		},
+		params: z.object({
+			id: z.coerce.number().int().positive(),
+		}),
+	}
+);

apps/backend/src/handlers/catalog/song/lyrics/update.ts

@@ -0,0 +1,39 @@
+import { Elysia } from "elysia";
+import {
+	ErrorResponseSchema,
+	SongLyricsUpdateRequestSchema,
+	SongLyricsResponseSchema,
+	songService,
+} from "@cvsa/core";
+import { authMiddleware } from "@/middlewares";
+import { traceTask } from "@/common/trace";
+import z from "zod";
+
+export const songLyricsUpdateHandler = new Elysia({ name: "songLyricsUpdateHandler" })
+	.use(authMiddleware)
+	.patch(
+		"/song/:id/lyric/:lyricId",
+		async ({ body, params, status }) => {
+			const lyric = await traceTask("songService.updateLyric", async () => {
+				return await songService.updateLyric(params.id, params.lyricId, body);
+			});
+			return status(200, lyric);
+		},
+		{
+			body: SongLyricsUpdateRequestSchema,
+			detail: {
+				summary: "Update Song Lyric",
+				description: "Update a specific lyrics item for a song. Requires authentication.",
+			},
+			response: {
+				200: SongLyricsResponseSchema,
+				400: ErrorResponseSchema,
+				401: ErrorResponseSchema,
+				404: ErrorResponseSchema,
+			},
+			params: z.object({
+				id: z.coerce.number().int().positive(),
+				lyricId: z.coerce.number().int().positive(),
+			}),
+		}
+	);

apps/backend/src/handlers/catalog/song/update.ts

@@ -1,8 +1,12 @@
 import { Elysia } from "elysia";
 import { z } from "zod";
-import { UpdateSongRequestSchema, ErrorResponseSchema, songService } from "@cvsa/core";
+import {
+	UpdateSongRequestSchema,
+	ErrorResponseSchema,
+	songService,
+	SongResponseSchema,
+} from "@cvsa/core";
 import { authMiddleware } from "@/middlewares";
-import { SongSchema } from "@cvsa/db";
 import { traceTask } from "@/common/trace";
 
 export const songUpdateHandler = new Elysia({ name: "songUpdateHandler" })
@@ -26,7 +30,7 @@ export const songUpdateHandler = new Elysia({ name: "songUpdateHandler" })
 					"Update metadata of an existing song identified by its ID. Requires authentication.",
 			},
 			response: {
-				200: SongSchema,
+				200: SongResponseSchema,
 				400: ErrorResponseSchema,
 				401: ErrorResponseSchema,
 				404: ErrorResponseSchema,

apps/backend/tests/auth.test.ts

@@ -1,4 +1,4 @@
-import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { treaty } from "@elysiajs/eden";
 import { app } from "@/index";
 import { prisma } from "@cvsa/db";