feat: enhance API route naming conventions and structure

- Added comprehensive guidelines for API route naming and structure in `ROUTE_NAMING_BEST_PRACTICES.md`.
- Updated `ARCHITECHTURE.md` to reference the new best practices document.
- Refactored course-related routes to follow new naming conventions, including changes to endpoint paths and validation schemas.
- Removed the deprecated course clone route and integrated cloning functionality directly into the course routes.
- Adjusted various API methods to ensure consistent usage of HTTP methods and parameter structures across the application.

apps/api/src/routes/course/clone.ts

@@ -1,32 +0,0 @@
-import type { CloneCourseErrorResponse, CloneCourseResponse } from '@api/types/database';
-
-import { Hono } from '@api/utils/hono';
-import { ZCourseClone } from '@cio/utils/validation/course';
-import { authMiddleware } from '@api/middlewares/auth';
-import { cloneCourse } from '@api/services/course/clone';
-import { zValidator } from '@hono/zod-validator';
-
-export const cloneRouter = new Hono().post('/', authMiddleware, zValidator('json', ZCourseClone), async (c) => {
-  try {
-    const validatedData = c.req.valid('json');
-    const { id, title, description, slug, organizationId } = validatedData;
-
-    const user = c.get('user');
-
-    // Clone the course
-    const newCourse = await cloneCourse(id, title, user.id, description, slug, organizationId);
-
-    const successResponse: CloneCourseResponse = {
-      success: true,
-      course: newCourse
-    };
-    return c.json(successResponse, 200);
-  } catch (error) {
-    console.error('Error cloning course:', error);
-    const errorResponse: CloneCourseErrorResponse = {
-      error: 'Failed to clone course',
-      details: error instanceof Error ? error.message : 'Unknown error'
-    };
-    return c.json(errorResponse, 500);
-  }
-});

apps/api/src/routes/course/course.ts

@@ -1,49 +1,94 @@
-import { ZCertificateDownload, ZCourseDownloadContent } from '@cio/utils/validation/course';
+import {
+  ZCertificateDownload,
+  ZCourseClone,
+  ZCourseCloneParam,
+  ZCourseDownloadContent,
+  ZCourseDownloadParam
+} from '@cio/utils/validation/course';
 
 import { Hono } from '@api/utils/hono';
-import { cloneRouter } from '@api/routes/course/clone';
+import { authMiddleware } from '@api/middlewares/auth';
+import { cloneCourse } from '@api/services/course/clone';
 import { generateCertificate } from '@api/utils/certificate';
 import { generateCoursePdf } from '@api/utils/course';
+import { handleError } from '@api/utils/errors';
 import { katexRouter } from '@api/routes/course/katex';
 import { lessonRouter } from '@api/routes/course/lesson';
 import { presignRouter } from '@api/routes/course/presign';
 import { zValidator } from '@hono/zod-validator';
 
 export const courseRouter = new Hono()
-  .post('/download/certificate', zValidator('json', ZCertificateDownload), async (c) => {
-    const validatedData = c.req.valid('json');
+  .post(
+    '/:courseId/download/certificate',
+    zValidator('param', ZCourseDownloadParam),
+    zValidator('json', ZCertificateDownload),
+    async (c) => {
+      const validatedData = c.req.valid('json');
 
-    const result = await generateCertificate(validatedData);
+      const result = await generateCertificate(validatedData);
 
-    c.header('Content-Type', 'application/pdf');
-    c.header('Content-Disposition', `attachment; filename="certificate-${validatedData.courseName}.pdf"`);
+      c.header('Content-Type', 'application/pdf');
+      c.header('Content-Disposition', `attachment; filename="certificate-${validatedData.courseName}.pdf"`);
 
-    return c.body(
-      new ReadableStream({
-        start(controller) {
-          controller.enqueue(result);
-          controller.close();
-        }
-      })
-    );
-  })
-  .post('/download/content', zValidator('json', ZCourseDownloadContent), async (c) => {
-    const validatedData = c.req.valid('json');
+      return c.body(
+        new ReadableStream({
+          start(controller) {
+            controller.enqueue(result);
+            controller.close();
+          }
+        })
+      );
+    }
+  )
+  .post(
+    '/:courseId/download/content',
+    zValidator('param', ZCourseDownloadParam),
+    zValidator('json', ZCourseDownloadContent),
+    async (c) => {
+      const validatedData = c.req.valid('json');
 
-    const pdfBuffer = await generateCoursePdf(validatedData);
+      const pdfBuffer = await generateCoursePdf(validatedData);
 
-    c.header('Content-Type', 'application/pdf');
+      c.header('Content-Type', 'application/pdf');
 
-    return c.body(
-      new ReadableStream({
-        start(controller) {
-          controller.enqueue(pdfBuffer);
-          controller.close();
-        }
-      })
-    );
-  })
+      return c.body(
+        new ReadableStream({
+          start(controller) {
+            controller.enqueue(pdfBuffer);
+            controller.close();
+          }
+        })
+      );
+    }
+  )
+  .post(
+    '/:courseId/clone',
+    authMiddleware,
+    zValidator('param', ZCourseCloneParam),
+    zValidator('json', ZCourseClone),
+    async (c) => {
+      try {
+        const { courseId } = c.req.valid('param');
+        const validatedData = c.req.valid('json');
+        const { title, description, slug, organizationId } = validatedData;
+
+        const user = c.get('user');
+
+        // Clone the course
+        const newCourse = await cloneCourse(courseId, title, user.id, description, slug, organizationId);
+
+        return c.json(
+          {
+            success: true,
+            course: newCourse
+          },
+          200
+        );
+      } catch (error) {
+        return handleError(c, error, 'Failed to clone course');
+      }
+    }
+  )
   .route('/katex', katexRouter)
   .route('/lesson', lessonRouter)
-  .route('/presign', presignRouter)
-  .route('/clone', cloneRouter);
+  .route('/presign', presignRouter);

apps/api/src/routes/course/katex.ts

@@ -1,7 +1,7 @@
-import { Hono } from '@api/utils/hono';
+import * as z from 'zod';
 
+import { Hono } from '@api/utils/hono';
 import katex from 'katex';
-import { z } from 'zod';
 
 export const katexRouter = new Hono().get('/', async (c) => {
   try {