feat: update routing to use name-based identifiers for projects and devlogs, enhancing URL clarity and consistency

Author: Marvin Zhang

packages/web/ROUTING.md

@@ -2,30 +2,33 @@
 
 ## Overview
 
-The web package uses Next.js 14 App Router with hierarchical routing structure that matches the API endpoints. This provides better organization and clearer URL structure for project-scoped operations.
+The web package uses Next.js 14 App Router with hierarchical routing structure that matches the API endpoints. This
+provides better organization and clearer URL structure for project-scoped operations.
 
 ## Route Structure
 
 ### Hierarchical Project-Based Routes (Primary)
+
 ```
 /                                           - Dashboard (homepage)
 /projects                                   - Project management page
-/projects/[id]                             - Project details page
-/projects/[id]/devlogs                     - List of devlogs for specific project
-/projects/[id]/devlogs/create              - Create new devlog in specific project
-/projects/[id]/devlogs/[devlogId]          - Individual devlog details within project
+/projects/[name]                            - Project details page
+/projects/[name]/devlogs                    - List of devlogs for specific project
+/projects/[name]/devlogs/[id]               - Individual devlog details within project
 ```
 
 ````markdown
 # Routing Implementation for @codervisor/devlog-web
 
 ## Overview
 
-The web package uses Next.js 14 App Router with hierarchical routing structure that matches the API endpoints. This provides better organization and clearer URL structure for project-scoped operations.
+The web package uses Next.js 14 App Router with hierarchical routing structure that matches the API endpoints. This
+provides better organization and clearer URL structure for project-scoped operations.
 
 ## Route Structure
 
 ### Hierarchical Project-Based Routes (Primary)
+
 ```
 /                                           - Redirects to /projects
 /projects                                   - Project list page (main entry point)
@@ -38,11 +41,14 @@ The web package uses Next.js 14 App Router with hierarchical routing structure t
 ## Key Changes Made
 
 ### Route Purpose Updates
+
 - **`/` (Homepage)**: Now redirects to `/projects` as the main entry point
 - **`/projects`**: Project list/management page - browse and manage all projects
-- **`/projects/[id]`**: Project dashboard - overview with stats, charts, and recent devlogs (formerly the homepage dashboard)
+- **`/projects/[id]`**: Project dashboard - overview with stats, charts, and recent devlogs (formerly the homepage
+  dashboard)
 
 ### Navigation Flow
+
 1. **User visits `/`** → Automatically redirected to `/projects`
 2. **User browses projects** at `/projects` → Can view all projects and create new ones
 3. **User selects a project** → Goes to `/projects/[id]` for that project's dashboard
@@ -79,16 +85,19 @@ app/
 ## Component Responsibilities
 
 ### ProjectManagementPage (/projects)
+
 - **Primary function**: Project list and management interface
 - **Features**: Browse projects, create new projects, view project cards
 - **Navigation**: Links to individual project dashboards
 
 ### ProjectDetailsPage (/projects/[id])
+
 - **Primary function**: Project-specific dashboard and overview
 - **Features**: Project stats, time series charts, recent devlogs, overview stats
 - **Context**: Sets project context for the entire project section
 
 ### DashboardPage Component
+
 - **Usage**: Embedded in ProjectDetailsPage for project-specific dashboards
 - **Features**: Stats visualization, time series data, recent devlogs display
 - **Scope**: Project-scoped rather than global

packages/web/app/api/projects/[name]/devlogs/[devlogId]/notes/[noteId]/route.ts

@@ -14,7 +14,7 @@ const UpdateNoteBodySchema = z.object({
   category: z.string().optional(),
 });
 
-// GET /api/projects/[name]/devlogs/[devlogId]/notes/[noteId] - Get specific note
+// GET /api/projects/[name]/devlogs/[id]/notes/[noteId] - Get specific note
 export async function GET(
   request: NextRequest,
   { params }: { params: { name: string; devlogId: string; noteId: string } },
@@ -53,7 +53,7 @@ export async function GET(
   }
 }
 
-// PUT /api/projects/[name]/devlogs/[devlogId]/notes/[noteId] - Update specific note
+// PUT /api/projects/[name]/devlogs/[id]/notes/[noteId] - Update specific note
 export async function PUT(
   request: NextRequest,
   { params }: { params: { name: string; devlogId: string; noteId: string } },
@@ -106,7 +106,7 @@ export async function PUT(
   }
 }
 
-// DELETE /api/projects/[name]/devlogs/[devlogId]/notes/[noteId] - Delete specific note
+// DELETE /api/projects/[name]/devlogs/[id]/notes/[noteId] - Delete specific note
 export async function DELETE(
   request: NextRequest,
   { params }: { params: { name: string; devlogId: string; noteId: string } },

packages/web/app/api/projects/[name]/devlogs/[devlogId]/notes/route.ts

@@ -8,7 +8,7 @@ import { DevlogAddNoteBodySchema, DevlogUpdateWithNoteBodySchema } from '@/schem
 // Mark this route as dynamic to prevent static generation
 export const dynamic = 'force-dynamic';
 
-// GET /api/projects/[name]/devlogs/[devlogId]/notes - List notes for a devlog entry
+// GET /api/projects/[name]/devlogs/[id]/notes - List notes for a devlog entry
 export async function GET(
   request: NextRequest,
   { params }: { params: { name: string; devlogId: string } },
@@ -68,7 +68,7 @@ export async function GET(
   }
 }
 
-// POST /api/projects/[name]/devlogs/[devlogId]/notes - Add note to devlog entry
+// POST /api/projects/[name]/devlogs/[id]/notes - Add note to devlog entry
 export async function POST(
   request: NextRequest,
   { params }: { params: { name: string; devlogId: string } },
@@ -118,7 +118,7 @@ export async function POST(
   }
 }
 
-// PUT /api/projects/[name]/devlogs/[devlogId]/notes - Update devlog and add note in one operation
+// PUT /api/projects/[name]/devlogs/[id]/notes - Update devlog and add note in one operation
 export async function PUT(
   request: NextRequest,
   { params }: { params: { name: string; devlogId: string } },

packages/web/app/api/projects/[name]/devlogs/[devlogId]/route.ts

@@ -6,7 +6,7 @@ import { RealtimeEventType } from '@/lib/realtime';
 // Mark this route as dynamic to prevent static generation
 export const dynamic = 'force-dynamic';
 
-// GET /api/projects/[name]/devlogs/[devlogId] - Get specific devlog entry
+// GET /api/projects/[name]/devlogs/[id] - Get specific devlog entry
 export async function GET(
   request: NextRequest,
   { params }: { params: { name: string; devlogId: string } },
@@ -55,7 +55,7 @@ export async function GET(
   }
 }
 
-// PUT /api/projects/[name]/devlogs/[devlogId] - Update devlog entry
+// PUT /api/projects/[name]/devlogs/[id] - Update devlog entry
 export async function PUT(
   request: NextRequest,
   { params }: { params: { name: string; devlogId: string } },
@@ -106,7 +106,7 @@ export async function PUT(
   }
 }
 
-// DELETE /api/projects/[name]/devlogs/[devlogId] - Delete devlog entry
+// DELETE /api/projects/[name]/devlogs/[id] - Delete devlog entry
 export async function DELETE(
   request: NextRequest,
   { params }: { params: { name: string; devlogId: string } },

packages/web/app/lib/api/api-utils.ts

@@ -53,7 +53,7 @@ export const RouteParams = {
 
   /**
    * Parse project name and devlog ID parameters (name-only routing for projects)
-   * Usage: /api/projects/[name]/devlogs/[devlogId]
+   * Usage: /api/projects/[name]/devlogs/[id]
    */
   parseProjectNameAndDevlogId(params: { name: string; devlogId: string }) {
     try {

packages/web/app/lib/api/devlog-api-client.ts

@@ -3,6 +3,7 @@ import type {
   DevlogFilter,
   DevlogId,
   DevlogNote,
+  DevlogNoteCategory,
   DevlogPriority,
   DevlogStats,
   DevlogStatus,
@@ -13,7 +14,6 @@ import type {
   TimeSeriesStats,
 } from '@codervisor/devlog-core';
 import { apiClient } from './api-client';
-import { CreateNoteRequest, UpdateNoteRequest } from '@/lib';
 
 export interface CreateDevlogRequest {
   title: string;
@@ -40,6 +40,16 @@ export interface BatchUpdateRequest {
   tags?: string[];
 }
 
+export interface CreateNoteRequest {
+  content: string;
+  category?: DevlogNoteCategory;
+}
+
+export interface UpdateNoteRequest {
+  content?: string;
+  category?: DevlogNoteCategory;
+}
+
 export interface BatchNoteRequest {
   content: string;
   category?: string;
@@ -107,7 +117,10 @@ export class DevlogApiClient {
    * Update an existing devlog
    */
   async update(devlogId: DevlogId, data: UpdateDevlogRequest): Promise<DevlogEntry> {
-    return apiClient.put<DevlogEntry>(`/api/projects/${this.projectName}/devlogs/${devlogId}`, data);
+    return apiClient.put<DevlogEntry>(
+      `/api/projects/${this.projectName}/devlogs/${devlogId}`,
+      data,
+    );
   }
 
   /**

packages/web/app/lib/api/index.ts

@@ -5,4 +5,3 @@
 
 export * from './api-client';
 export * from './devlog-api-client';
-export * from './note-api-client';

packages/web/app/lib/api/note-api-client.ts

@@ -63,46 +63,9 @@ export const RouteParamParsers = {
   /**
    * Parse project route parameters
    * For routes like: /projects/[name]/...
+   * @deprecated
    */
   parseProjectParams(params: { id: string }): ParsedProjectParams {
     return parseProjectIdentifier(params.id, 'project identifier');
   },
-
-  /**
-   * Parse project + devlog route parameters
-   * For routes like: /projects/[name]/devlogs/[devlogId]/...
-   */
-  parseDevlogParams(params: { id: string; devlogId: string }): ParsedDevlogParams {
-    const projectInfo = parseProjectIdentifier(params.id, 'project identifier');
-    return {
-      ...projectInfo,
-      devlogId: parseId(params.devlogId, 'devlog ID') as DevlogId,
-    };
-  },
-
-  /**
-   * Parse single devlog ID parameter
-   * For routes like: /devlogs/[name]/...
-   */
-  parseDevlogId(params: { id: string }): { devlogId: DevlogId } {
-    return {
-      devlogId: parseId(params.id, 'devlog ID') as DevlogId,
-    };
-  },
 };
-
-/**
- * Hook for parsing route parameters in client components
- */
-export function useRouteParams<P extends Record<string, string>, T>(
-  params: P,
-  parser: (params: P) => T,
-): T {
-  try {
-    return parser(params);
-  } catch (error) {
-    throw new Error(
-      `Route parameter error: ${error instanceof Error ? error.message : 'Invalid parameters'}`,
-    );
-  }
-}

packages/web/app/lib/routing/route-params.ts

@@ -10,10 +10,10 @@ interface ProjectContextValue {
 
 const ProjectContext = createContext<ProjectContextValue | null>(null);
 
-export function ProjectProvider({ 
-  children, 
-  project 
-}: { 
+export function ProjectProvider({
+  children,
+  project,
+}: {
   children: React.ReactNode;
   project: Project;
 }) {
@@ -22,11 +22,7 @@ export function ProjectProvider({
     projectName: project.name,
   };
 
-  return (
-    <ProjectContext.Provider value={value}>
-      {children}
-    </ProjectContext.Provider>
-  );
+  return <ProjectContext.Provider value={value}>{children}</ProjectContext.Provider>;
 }
 
 export function useProject(): ProjectContextValue {
@@ -40,4 +36,4 @@ export function useProject(): ProjectContextValue {
 export function useProjectName(): string {
   const { projectName } = useProject();
   return projectName;
-}
+}