feat(onboarding): add onboarding module and integrate with dashboard; add Prisma migration

- backend: add onboarding module (`onboardingController`, `onboardingRoutes`, `composition`)
- backend: register onboarding routes in `app.ts` and DI in `container.ts`
- prisma: update `schema.prisma` and add `20250820054225_onboarding` migration
- frontend: add `features/dashboard/onboarding/api.ts` and update `OnboardingProvider`
- frontend: wire onboarding into dashboard page and `Dashboard` component

DB: run Prisma migrations after pulling these changes

Author: markmdev

apps/backend/prisma/migrations/20250820054225_onboarding/migration.sql

@@ -0,0 +1,30 @@
+/*
+  Warnings:
+
+  - You are about to drop the `Session` table. If the table is not empty, all the data it contains will be lost.
+
+*/
+-- CreateEnum
+CREATE TYPE "OnbStatus" AS ENUM ('completed');
+
+-- DropForeignKey
+ALTER TABLE "Session" DROP CONSTRAINT "Session_userId_fkey";
+
+-- DropTable
+DROP TABLE "Session";
+
+-- CreateTable
+CREATE TABLE "Onboarding" (
+    "id" SERIAL NOT NULL,
+    "status" "OnbStatus" NOT NULL,
+    "completed_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "userId" INTEGER NOT NULL,
+
+    CONSTRAINT "Onboarding_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "Onboarding_userId_key" ON "Onboarding"("userId");
+
+-- AddForeignKey
+ALTER TABLE "Onboarding" ADD CONSTRAINT "Onboarding_userId_fkey" FOREIGN KEY ("userId") REFERENCES "User"("id") ON DELETE RESTRICT ON UPDATE CASCADE;

apps/backend/prisma/schema.prisma

@@ -48,6 +48,15 @@ model User {
   userVocabulary UserVocabulary[]
   UnknownWord    UnknownWord[]
   RefreshToken   RefreshToken[]
+  onboarding Onboarding?
+}
+
+model Onboarding {
+  id Int @id @default(autoincrement())
+  status OnbStatus
+  completed_at DateTime @default(now())
+  user User @relation(fields: [userId], references: [id])
+  userId Int @unique
 }
 
 model RefreshToken {
@@ -80,3 +89,7 @@ enum SessionStatus {
   completed
   expired
 }
+
+enum OnbStatus {
+  completed
+}

apps/backend/src/app.ts

@@ -13,6 +13,7 @@ import { closeRedisConnection, connectRedis } from "./services/redis/redisClient
 import {
   authRouter,
   jobsModule,
+  onboardingModule,
   storyModule,
   unknownWordModule,
   vocabAssessmentModule,
@@ -49,6 +50,7 @@ app.use("/api/unknown-words", unknownWordModule.router);
 app.use("/api/auth", authRouter);
 app.use("/api/vocab-assessment", vocabAssessmentModule.router);
 app.use("/api/jobs", jobsModule.router);
+app.use("/api/onboarding", onboardingModule.router);
 
 app.get("/healthz", (req, res) => {
   res.status(200).send("OK");

apps/backend/src/cache/redisStoryCache.ts

@@ -24,7 +24,7 @@ export class RedisStoryCache extends BaseRedisCache {
         unknownWords: storyJson.unknownWords || [],
       };
     } catch (error) {
-      logger.error("Failed to parse cached story", { error, storyString });
+      logger.error("Failed to parse cached story", error, storyString);
       throw new RedisError("Invalid cached story format", error, { storyString });
     }
   }

apps/backend/src/container.ts

@@ -2,6 +2,7 @@ import { createAuthMiddleware } from "./middlewares/authMiddleware";
 import { buildAuthRouter } from "./modules/auth/authRoutes";
 import { createAuthModule } from "./modules/auth/composition";
 import { createJobsModule } from "./modules/jobs/composition";
+import { createOnboardingModule } from "./modules/onboarding/composition";
 import { createSessionModule } from "./modules/session/composition";
 import { createStoryModule } from "./modules/story/composition";
 import { TextToSpeechService } from "./modules/story/services/audioAssembler/textToSpeechService";
@@ -66,3 +67,8 @@ export const vocabAssessmentModule = createVocabAssessmentModule({
   sessionService: sessionModule.service,
   vocabularyService: vocabularyModule.service,
 });
+
+export const onboardingModule = createOnboardingModule({
+  prisma,
+  authMiddleware,
+});

apps/backend/src/modules/onboarding/composition.ts

@@ -0,0 +1,12 @@
+import { PrismaClient } from "@prisma/client";
+import { OnboardingController } from "./onboardingController";
+import { buildOnboardingRouter } from "./onboardingRoutes";
+import { NextFunction, Request, Response } from "express";
+
+export function createOnboardingModule(deps: {
+  prisma: PrismaClient;
+  authMiddleware: (req: Request, res: Response, next: NextFunction) => void;
+}) {
+  const controller = new OnboardingController(deps.prisma);
+  return { router: buildOnboardingRouter(controller, deps.authMiddleware) };
+}

apps/backend/src/modules/onboarding/onboardingController.ts

@@ -0,0 +1,46 @@
+import { PrismaError } from "@/errors/PrismaError";
+import { formatResponse } from "@/middlewares/responseFormatter";
+import { AuthedRequest } from "@/types/types";
+import { PrismaClient } from "@prisma/client";
+import { Response } from "express";
+
+export class OnboardingController {
+  constructor(private prisma: PrismaClient) {}
+
+  completeOnboarding = async (req: AuthedRequest, res: Response) => {
+    const { userId } = req.user;
+    try {
+      await this.prisma.onboarding.upsert({
+        where: {
+          userId,
+        },
+        update: {
+          status: "completed",
+        },
+        create: {
+          user: {
+            connect: { id: userId },
+          },
+          status: "completed",
+        },
+      });
+    } catch (error) {
+      throw new PrismaError("Failed on complete onboarding", error, { userId });
+    }
+    res.status(200).json(formatResponse({ success: true }));
+  };
+
+  checkOnboarding = async (req: AuthedRequest, res: Response) => {
+    const { userId } = req.user;
+    try {
+      const result = await this.prisma.onboarding.findFirst({ where: { userId } });
+      if (result) {
+        res.status(200).json(formatResponse({ status: "completed" }));
+      } else {
+        res.status(200).json(formatResponse({ status: "not_started" }));
+      }
+    } catch (error) {
+      throw new PrismaError("Failed on check onboarding status", error, { userId });
+    }
+  };
+}

apps/backend/src/modules/onboarding/onboardingRoutes.ts

@@ -0,0 +1,15 @@
+import { NextFunction, Request, Response, Router } from "express";
+import { OnboardingController } from "./onboardingController";
+import { asyncHandler } from "@/middlewares/asyncHandler";
+
+export function buildOnboardingRouter(
+  controller: OnboardingController,
+  authMiddleware: (req: Request, res: Response, next: NextFunction) => void
+) {
+  const router = Router();
+
+  router.post("/complete", authMiddleware, asyncHandler(controller.completeOnboarding));
+  router.get("/check", authMiddleware, asyncHandler(controller.checkOnboarding));
+
+  return router;
+}

apps/backend/src/services/redis/baseRedisCache.ts

@@ -26,7 +26,7 @@ export abstract class BaseRedisCache {
       if (!value) return null;
       return JSON.parse(value) as T;
     } catch (error) {
-      logger.error("[cache] getKey error", { error, key });
+      logger.error("[cache] getKey error", error, key);
       return null;
     }
   }
@@ -46,7 +46,7 @@ export abstract class BaseRedisCache {
       const value = await this.redis.lRange(key, 0, -1);
       return value;
     } catch (error) {
-      logger.error("[cache] lRange error", { error, key });
+      logger.error("[cache] lRange error", error, key);
       return [];
     }
   }

apps/frontend/src/app/(protected)/dashboard/page.tsx

@@ -2,7 +2,7 @@
 
 import { Story } from "@/features/story/types";
 import { ApiError } from "@/types/ApiError";
-import { useCallback, useEffect } from "react";
+import { useCallback } from "react";
 import Dashboard from "@/components/Dashboard";
 import { useWordStatus } from "@/features/story/hooks/useWordStatus";
 import { useStories } from "@/features/story/hooks/useStories";