feat(platform): residential module + admin UI + reliability fixes

Residential platform
- New schema: residentialClients, residentialInterests (separate from
  marina/yacht clients) with migration 0010
- Service layer with CRUD + audit + sockets + per-port portal toggle
- v1 + public API routes (/api/v1/residential/*, /api/public/residential-inquiries)
- List + detail pages with inline editing for clients and interests
- Per-user residentialAccess toggle on userPortRoles (migration 0011)
- Permission keys: residential_clients, residential_interests
- Sidebar nav + role form integration
- Smoke spec covering page loads, UI create flow, public endpoint

Admin & shared UI
- Admin → Forms (form templates CRUD) with validators + service
- Notification preferences page (in-app + email per type)
- Email composition + accounts list + threads view
- Branded auth shell shared across CRM + portal auth surfaces
- Inline editing extended to yacht/company/interest detail pages
- InlineTagEditor + per-entity tags endpoints (yachts, companies)
- Notes service polymorphic across clients/interests/yachts/companies
- Client list columns: yachtCount + companyCount badges
- Reservation file-download via presigned URL (replaces stale <a href>)

Route handler refactor
- Extracted yachts/companies/berths reservation handlers to sibling
  handlers.ts files (Next.js 15 route.ts only allows specific exports)

Reliability fixes
- apiFetch double-stringify bug fixed across 13 components
  (apiFetch already JSON.stringifies its body; passing a stringified
  body produced double-encoded JSON which failed zod validation)
- SocketProvider gated behind useSyncExternalStore-based mount check
  to avoid useSession() SSR crashes under React 19 + Next 15
- apiFetch falls back to URL-pathname → port-id resolution when the
  Zustand store hasn't hydrated yet (fresh contexts, e2e tests)
- CRM invite flow (schema, service, route, email, dev script)
- Dashboard route → [portSlug]/dashboard/page.tsx + redirect
- Document the dev-server restart-after-migration gotcha in CLAUDE.md

Tests
- 5-case residential smoke spec
- Integration test updates for new service signatures

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/app/api/v1/admin/form-templates/[id]/route.ts

@@ -0,0 +1,58 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse, NotFoundError } from '@/lib/errors';
+import {
+  deleteFormTemplate,
+  getFormTemplateById,
+  updateFormTemplate,
+} from '@/lib/services/form-templates.service';
+import { updateFormTemplateSchema } from '@/lib/validators/form-templates';
+
+export const GET = withAuth(
+  withPermission('admin', 'manage_forms', async (_req, ctx, params) => {
+    try {
+      if (!params.id) throw new NotFoundError('Form template');
+      const tpl = await getFormTemplateById(params.id, ctx.portId);
+      return NextResponse.json({ data: tpl });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const PATCH = withAuth(
+  withPermission('admin', 'manage_forms', async (req, ctx, params) => {
+    try {
+      if (!params.id) throw new NotFoundError('Form template');
+      const body = await parseBody(req, updateFormTemplateSchema);
+      const tpl = await updateFormTemplate(params.id, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: tpl });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('admin', 'manage_forms', async (_req, ctx, params) => {
+    try {
+      if (!params.id) throw new NotFoundError('Form template');
+      await deleteFormTemplate(params.id, ctx.portId, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return new NextResponse(null, { status: 204 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/form-templates/route.ts

@@ -0,0 +1,35 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { createFormTemplate, listFormTemplates } from '@/lib/services/form-templates.service';
+import { createFormTemplateSchema } from '@/lib/validators/form-templates';
+
+export const GET = withAuth(
+  withPermission('admin', 'manage_forms', async (_req, ctx) => {
+    try {
+      const data = await listFormTemplates(ctx.portId);
+      return NextResponse.json({ data });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const POST = withAuth(
+  withPermission('admin', 'manage_forms', async (req, ctx) => {
+    try {
+      const body = await parseBody(req, createFormTemplateSchema);
+      const tpl = await createFormTemplate(ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: tpl }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/berths/[id]/reservations/handlers.ts

@@ -0,0 +1,65 @@
+import { and, eq } from 'drizzle-orm';
+import { NextResponse } from 'next/server';
+
+import { type RouteHandler } from '@/lib/api/helpers';
+import { parseBody, parseQuery } from '@/lib/api/route-helpers';
+import { db } from '@/lib/db';
+import { berths } from '@/lib/db/schema/berths';
+import { NotFoundError, errorResponse } from '@/lib/errors';
+import { createPending, listReservations } from '@/lib/services/berth-reservations.service';
+import { createPendingSchema, listReservationsSchema } from '@/lib/validators/reservations';
+
+// URL berthId is authoritative; make body berthId optional (ignored anyway).
+const createPendingBodySchema = createPendingSchema
+  .omit({ berthId: true })
+  .extend({ berthId: createPendingSchema.shape.berthId.optional() });
+
+async function assertBerthInPort(berthId: string, portId: string): Promise<void> {
+  const berth = await db.query.berths.findFirst({
+    where: and(eq(berths.id, berthId), eq(berths.portId, portId)),
+  });
+  if (!berth) throw new NotFoundError('Berth');
+}
+
+export const listHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    await assertBerthInPort(params.id!, ctx.portId);
+    const query = parseQuery(req, listReservationsSchema);
+    const result = await listReservations(ctx.portId, { ...query, berthId: params.id! });
+    const { page, limit } = query;
+    const totalPages = Math.ceil(result.total / limit);
+    return NextResponse.json({
+      data: result.data,
+      pagination: {
+        page,
+        pageSize: limit,
+        total: result.total,
+        totalPages,
+        hasNextPage: page < totalPages,
+        hasPreviousPage: page > 1,
+      },
+    });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const createHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    await assertBerthInPort(params.id!, ctx.portId);
+    const body = await parseBody(req, createPendingBodySchema);
+    const reservation = await createPending(
+      ctx.portId,
+      { ...body, berthId: params.id! },
+      {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      },
+    );
+    return NextResponse.json({ data: reservation }, { status: 201 });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};

src/app/api/v1/berths/[id]/reservations/route.ts

@@ -1,72 +1,6 @@
-import { and, eq } from 'drizzle-orm';
-import { NextResponse } from 'next/server';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 
-import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
-import { parseBody, parseQuery } from '@/lib/api/route-helpers';
-import { db } from '@/lib/db';
-import { berths } from '@/lib/db/schema/berths';
-import { NotFoundError, errorResponse } from '@/lib/errors';
-import { createPending, listReservations } from '@/lib/services/berth-reservations.service';
-import { createPendingSchema, listReservationsSchema } from '@/lib/validators/reservations';
-
-// URL berthId is authoritative; make body berthId optional (ignored anyway).
-const createPendingBodySchema = createPendingSchema
-  .omit({ berthId: true })
-  .extend({ berthId: createPendingSchema.shape.berthId.optional() });
-
-async function assertBerthInPort(berthId: string, portId: string): Promise<void> {
-  const berth = await db.query.berths.findFirst({
-    where: and(eq(berths.id, berthId), eq(berths.portId, portId)),
-  });
-  if (!berth) throw new NotFoundError('Berth');
-}
-
-export const listHandler: RouteHandler = async (req, ctx, params) => {
-  try {
-    await assertBerthInPort(params.id!, ctx.portId);
-
-    const query = parseQuery(req, listReservationsSchema);
-    // URL berthId is authoritative; override any client-supplied value.
-    const result = await listReservations(ctx.portId, { ...query, berthId: params.id! });
-    const { page, limit } = query;
-    const totalPages = Math.ceil(result.total / limit);
-    return NextResponse.json({
-      data: result.data,
-      pagination: {
-        page,
-        pageSize: limit,
-        total: result.total,
-        totalPages,
-        hasNextPage: page < totalPages,
-        hasPreviousPage: page > 1,
-      },
-    });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
-
-export const createHandler: RouteHandler = async (req, ctx, params) => {
-  try {
-    await assertBerthInPort(params.id!, ctx.portId);
-
-    const body = await parseBody(req, createPendingBodySchema);
-    // URL berthId is authoritative; any body-supplied berthId is ignored.
-    const reservation = await createPending(
-      ctx.portId,
-      { ...body, berthId: params.id! },
-      {
-        userId: ctx.userId,
-        portId: ctx.portId,
-        ipAddress: ctx.ipAddress,
-        userAgent: ctx.userAgent,
-      },
-    );
-    return NextResponse.json({ data: reservation }, { status: 201 });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
+import { listHandler, createHandler } from './handlers';
 
 export const GET = withAuth(withPermission('reservations', 'view', listHandler));
 export const POST = withAuth(withPermission('reservations', 'create', createHandler));

src/app/api/v1/companies/[id]/handlers.ts

@@ -0,0 +1,45 @@
+import { NextResponse } from 'next/server';
+
+import { type RouteHandler } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { getCompanyById, updateCompany, archiveCompany } from '@/lib/services/companies.service';
+import { updateCompanySchema } from '@/lib/validators/companies';
+
+export const getHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    const company = await getCompanyById(params.id!, ctx.portId);
+    return NextResponse.json({ data: company });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const patchHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    const body = await parseBody(req, updateCompanySchema);
+    const updated = await updateCompany(params.id!, ctx.portId, body, {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: updated });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const deleteHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    await archiveCompany(params.id!, ctx.portId, {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return new NextResponse(null, { status: 204 });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};

src/app/api/v1/companies/[id]/notes/[noteId]/route.ts

@@ -0,0 +1,63 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { createAuditLog } from '@/lib/audit';
+import { errorResponse, NotFoundError } from '@/lib/errors';
+import { updateNoteSchema } from '@/lib/validators/notes';
+import * as notesService from '@/lib/services/notes.service';
+
+export const PATCH = withAuth(
+  withPermission('companies', 'edit', async (req, ctx, params) => {
+    try {
+      const companyId = params.id;
+      const noteId = params.noteId;
+      if (!companyId) throw new NotFoundError('Company');
+      if (!noteId) throw new NotFoundError('Note');
+      const body = await parseBody(req, updateNoteSchema);
+      const note = await notesService.update(ctx.portId, 'companies', companyId, noteId, body);
+
+      void createAuditLog({
+        userId: ctx.userId,
+        portId: ctx.portId,
+        action: 'update',
+        entityType: 'company_note',
+        entityId: noteId,
+        metadata: { companyId },
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+
+      return NextResponse.json({ data: note });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('companies', 'edit', async (_req, ctx, params) => {
+    try {
+      const companyId = params.id;
+      const noteId = params.noteId;
+      if (!companyId) throw new NotFoundError('Company');
+      if (!noteId) throw new NotFoundError('Note');
+      await notesService.deleteNote(ctx.portId, 'companies', companyId, noteId);
+
+      void createAuditLog({
+        userId: ctx.userId,
+        portId: ctx.portId,
+        action: 'delete',
+        entityType: 'company_note',
+        entityId: noteId,
+        metadata: { companyId },
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+
+      return new NextResponse(null, { status: 204 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/companies/[id]/notes/route.ts

@@ -0,0 +1,47 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { createAuditLog } from '@/lib/audit';
+import { errorResponse, NotFoundError } from '@/lib/errors';
+import { createNoteSchema } from '@/lib/validators/notes';
+import * as notesService from '@/lib/services/notes.service';
+
+export const GET = withAuth(
+  withPermission('companies', 'view', async (_req, ctx, params) => {
+    try {
+      const companyId = params.id;
+      if (!companyId) throw new NotFoundError('Company');
+      const notes = await notesService.listForEntity(ctx.portId, 'companies', companyId);
+      return NextResponse.json({ data: notes });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const POST = withAuth(
+  withPermission('companies', 'edit', async (req, ctx, params) => {
+    try {
+      const companyId = params.id;
+      if (!companyId) throw new NotFoundError('Company');
+      const body = await parseBody(req, createNoteSchema);
+      const note = await notesService.create(ctx.portId, 'companies', companyId, ctx.userId, body);
+
+      void createAuditLog({
+        userId: ctx.userId,
+        portId: ctx.portId,
+        action: 'create',
+        entityType: 'company_note',
+        entityId: note.id,
+        metadata: { companyId },
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+
+      return NextResponse.json({ data: note }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/companies/[id]/route.ts

@@ -1,48 +1,6 @@
-import { NextResponse } from 'next/server';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 
-import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
-import { parseBody } from '@/lib/api/route-helpers';
-import { errorResponse } from '@/lib/errors';
-import { getCompanyById, updateCompany, archiveCompany } from '@/lib/services/companies.service';
-import { updateCompanySchema } from '@/lib/validators/companies';
-
-export const getHandler: RouteHandler = async (req, ctx, params) => {
-  try {
-    const company = await getCompanyById(params.id!, ctx.portId);
-    return NextResponse.json({ data: company });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
-
-export const patchHandler: RouteHandler = async (req, ctx, params) => {
-  try {
-    const body = await parseBody(req, updateCompanySchema);
-    const updated = await updateCompany(params.id!, ctx.portId, body, {
-      userId: ctx.userId,
-      portId: ctx.portId,
-      ipAddress: ctx.ipAddress,
-      userAgent: ctx.userAgent,
-    });
-    return NextResponse.json({ data: updated });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
-
-export const deleteHandler: RouteHandler = async (req, ctx, params) => {
-  try {
-    await archiveCompany(params.id!, ctx.portId, {
-      userId: ctx.userId,
-      portId: ctx.portId,
-      ipAddress: ctx.ipAddress,
-      userAgent: ctx.userAgent,
-    });
-    return new NextResponse(null, { status: 204 });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
+import { getHandler, patchHandler, deleteHandler } from './handlers';
 
 export const GET = withAuth(withPermission('companies', 'view', getHandler));
 export const PATCH = withAuth(withPermission('companies', 'edit', patchHandler));

src/app/api/v1/companies/[id]/tags/route.ts

@@ -0,0 +1,28 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { setCompanyTags } from '@/lib/services/companies.service';
+
+const setTagsSchema = z.object({
+  tagIds: z.array(z.string()),
+});
+
+export const PUT = withAuth(
+  withPermission('companies', 'edit', async (req, ctx, params) => {
+    try {
+      const { tagIds } = await parseBody(req, setTagsSchema);
+      await setCompanyTags(params.id!, ctx.portId, tagIds, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ success: true });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/companies/handlers.ts

@@ -0,0 +1,44 @@
+import { NextResponse } from 'next/server';
+
+import { type RouteHandler } from '@/lib/api/helpers';
+import { parseQuery, parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { listCompanies, createCompany } from '@/lib/services/companies.service';
+import { listCompaniesSchema, createCompanySchema } from '@/lib/validators/companies';
+
+export const listHandler: RouteHandler = async (req, ctx) => {
+  try {
+    const query = parseQuery(req, listCompaniesSchema);
+    const result = await listCompanies(ctx.portId, query);
+    const { page, limit } = query;
+    const totalPages = Math.ceil(result.total / limit);
+    return NextResponse.json({
+      data: result.data,
+      pagination: {
+        page,
+        pageSize: limit,
+        total: result.total,
+        totalPages,
+        hasNextPage: page < totalPages,
+        hasPreviousPage: page > 1,
+      },
+    });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const createHandler: RouteHandler = async (req, ctx) => {
+  try {
+    const body = await parseBody(req, createCompanySchema);
+    const company = await createCompany(ctx.portId, body, {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: company }, { status: 201 });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};

src/app/api/v1/companies/route.ts

@@ -1,47 +1,6 @@
-import { NextResponse } from 'next/server';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 
-import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
-import { parseQuery, parseBody } from '@/lib/api/route-helpers';
-import { errorResponse } from '@/lib/errors';
-import { listCompanies, createCompany } from '@/lib/services/companies.service';
-import { listCompaniesSchema, createCompanySchema } from '@/lib/validators/companies';
-
-export const listHandler: RouteHandler = async (req, ctx) => {
-  try {
-    const query = parseQuery(req, listCompaniesSchema);
-    const result = await listCompanies(ctx.portId, query);
-    const { page, limit } = query;
-    const totalPages = Math.ceil(result.total / limit);
-    return NextResponse.json({
-      data: result.data,
-      pagination: {
-        page,
-        pageSize: limit,
-        total: result.total,
-        totalPages,
-        hasNextPage: page < totalPages,
-        hasPreviousPage: page > 1,
-      },
-    });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
-
-export const createHandler: RouteHandler = async (req, ctx) => {
-  try {
-    const body = await parseBody(req, createCompanySchema);
-    const company = await createCompany(ctx.portId, body, {
-      userId: ctx.userId,
-      portId: ctx.portId,
-      ipAddress: ctx.ipAddress,
-      userAgent: ctx.userAgent,
-    });
-    return NextResponse.json({ data: company }, { status: 201 });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
+import { listHandler, createHandler } from './handlers';
 
 export const GET = withAuth(withPermission('companies', 'view', listHandler));
 export const POST = withAuth(withPermission('companies', 'create', createHandler));

src/app/api/v1/residential/clients/[id]/route.ts

@@ -0,0 +1,55 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import {
+  archiveResidentialClient,
+  getResidentialClientById,
+  updateResidentialClient,
+} from '@/lib/services/residential.service';
+import { updateResidentialClientSchema } from '@/lib/validators/residential';
+
+export const GET = withAuth(
+  withPermission('residential_clients', 'view', async (req, ctx, params) => {
+    try {
+      const client = await getResidentialClientById(params.id!, ctx.portId);
+      return NextResponse.json({ data: client });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const PATCH = withAuth(
+  withPermission('residential_clients', 'edit', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, updateResidentialClientSchema);
+      const updated = await updateResidentialClient(params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: updated });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('residential_clients', 'delete', async (req, ctx, params) => {
+    try {
+      await archiveResidentialClient(params.id!, ctx.portId, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return new NextResponse(null, { status: 204 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/residential/clients/route.ts

@@ -0,0 +1,54 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseQuery, parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import {
+  createResidentialClient,
+  listResidentialClients,
+} from '@/lib/services/residential.service';
+import {
+  createResidentialClientSchema,
+  listResidentialClientsSchema,
+} from '@/lib/validators/residential';
+
+export const GET = withAuth(
+  withPermission('residential_clients', 'view', async (req, ctx) => {
+    try {
+      const query = parseQuery(req, listResidentialClientsSchema);
+      const result = await listResidentialClients(ctx.portId, query);
+      const { page, limit } = query;
+      const totalPages = Math.ceil(result.total / limit);
+      return NextResponse.json({
+        data: result.data,
+        pagination: {
+          page,
+          pageSize: limit,
+          total: result.total,
+          totalPages,
+          hasNextPage: page < totalPages,
+          hasPreviousPage: page > 1,
+        },
+      });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const POST = withAuth(
+  withPermission('residential_clients', 'create', async (req, ctx) => {
+    try {
+      const body = await parseBody(req, createResidentialClientSchema);
+      const client = await createResidentialClient(ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: client }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/residential/interests/[id]/route.ts

@@ -0,0 +1,55 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import {
+  archiveResidentialInterest,
+  getResidentialInterestById,
+  updateResidentialInterest,
+} from '@/lib/services/residential.service';
+import { updateResidentialInterestSchema } from '@/lib/validators/residential';
+
+export const GET = withAuth(
+  withPermission('residential_interests', 'view', async (req, ctx, params) => {
+    try {
+      const interest = await getResidentialInterestById(params.id!, ctx.portId);
+      return NextResponse.json({ data: interest });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const PATCH = withAuth(
+  withPermission('residential_interests', 'edit', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, updateResidentialInterestSchema);
+      const updated = await updateResidentialInterest(params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: updated });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('residential_interests', 'delete', async (req, ctx, params) => {
+    try {
+      await archiveResidentialInterest(params.id!, ctx.portId, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return new NextResponse(null, { status: 204 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/residential/interests/route.ts

@@ -0,0 +1,54 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseQuery, parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import {
+  createResidentialInterest,
+  listResidentialInterests,
+} from '@/lib/services/residential.service';
+import {
+  createResidentialInterestSchema,
+  listResidentialInterestsSchema,
+} from '@/lib/validators/residential';
+
+export const GET = withAuth(
+  withPermission('residential_interests', 'view', async (req, ctx) => {
+    try {
+      const query = parseQuery(req, listResidentialInterestsSchema);
+      const result = await listResidentialInterests(ctx.portId, query);
+      const { page, limit } = query;
+      const totalPages = Math.ceil(result.total / limit);
+      return NextResponse.json({
+        data: result.data,
+        pagination: {
+          page,
+          pageSize: limit,
+          total: result.total,
+          totalPages,
+          hasNextPage: page < totalPages,
+          hasPreviousPage: page > 1,
+        },
+      });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const POST = withAuth(
+  withPermission('residential_interests', 'create', async (req, ctx) => {
+    try {
+      const body = await parseBody(req, createResidentialInterestSchema);
+      const interest = await createResidentialInterest(ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: interest }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/yachts/[id]/handlers.ts

@@ -0,0 +1,45 @@
+import { NextResponse } from 'next/server';
+
+import { type RouteHandler } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { getYachtById, updateYacht, archiveYacht } from '@/lib/services/yachts.service';
+import { updateYachtSchema } from '@/lib/validators/yachts';
+
+export const getHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    const yacht = await getYachtById(params.id!, ctx.portId);
+    return NextResponse.json({ data: yacht });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const patchHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    const body = await parseBody(req, updateYachtSchema);
+    const updated = await updateYacht(params.id!, ctx.portId, body, {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: updated });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const deleteHandler: RouteHandler = async (req, ctx, params) => {
+  try {
+    await archiveYacht(params.id!, ctx.portId, {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return new NextResponse(null, { status: 204 });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};

src/app/api/v1/yachts/[id]/notes/[noteId]/route.ts

@@ -0,0 +1,63 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { createAuditLog } from '@/lib/audit';
+import { errorResponse, NotFoundError } from '@/lib/errors';
+import { updateNoteSchema } from '@/lib/validators/notes';
+import * as notesService from '@/lib/services/notes.service';
+
+export const PATCH = withAuth(
+  withPermission('yachts', 'edit', async (req, ctx, params) => {
+    try {
+      const yachtId = params.id;
+      const noteId = params.noteId;
+      if (!yachtId) throw new NotFoundError('Yacht');
+      if (!noteId) throw new NotFoundError('Note');
+      const body = await parseBody(req, updateNoteSchema);
+      const note = await notesService.update(ctx.portId, 'yachts', yachtId, noteId, body);
+
+      void createAuditLog({
+        userId: ctx.userId,
+        portId: ctx.portId,
+        action: 'update',
+        entityType: 'yacht_note',
+        entityId: noteId,
+        metadata: { yachtId },
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+
+      return NextResponse.json({ data: note });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('yachts', 'edit', async (_req, ctx, params) => {
+    try {
+      const yachtId = params.id;
+      const noteId = params.noteId;
+      if (!yachtId) throw new NotFoundError('Yacht');
+      if (!noteId) throw new NotFoundError('Note');
+      await notesService.deleteNote(ctx.portId, 'yachts', yachtId, noteId);
+
+      void createAuditLog({
+        userId: ctx.userId,
+        portId: ctx.portId,
+        action: 'delete',
+        entityType: 'yacht_note',
+        entityId: noteId,
+        metadata: { yachtId },
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+
+      return new NextResponse(null, { status: 204 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/yachts/[id]/notes/route.ts

@@ -0,0 +1,47 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { createAuditLog } from '@/lib/audit';
+import { errorResponse, NotFoundError } from '@/lib/errors';
+import { createNoteSchema } from '@/lib/validators/notes';
+import * as notesService from '@/lib/services/notes.service';
+
+export const GET = withAuth(
+  withPermission('yachts', 'view', async (_req, ctx, params) => {
+    try {
+      const yachtId = params.id;
+      if (!yachtId) throw new NotFoundError('Yacht');
+      const notes = await notesService.listForEntity(ctx.portId, 'yachts', yachtId);
+      return NextResponse.json({ data: notes });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const POST = withAuth(
+  withPermission('yachts', 'edit', async (req, ctx, params) => {
+    try {
+      const yachtId = params.id;
+      if (!yachtId) throw new NotFoundError('Yacht');
+      const body = await parseBody(req, createNoteSchema);
+      const note = await notesService.create(ctx.portId, 'yachts', yachtId, ctx.userId, body);
+
+      void createAuditLog({
+        userId: ctx.userId,
+        portId: ctx.portId,
+        action: 'create',
+        entityType: 'yacht_note',
+        entityId: note.id,
+        metadata: { yachtId },
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+
+      return NextResponse.json({ data: note }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/yachts/[id]/route.ts

@@ -1,48 +1,6 @@
-import { NextResponse } from 'next/server';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 
-import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
-import { parseBody } from '@/lib/api/route-helpers';
-import { errorResponse } from '@/lib/errors';
-import { getYachtById, updateYacht, archiveYacht } from '@/lib/services/yachts.service';
-import { updateYachtSchema } from '@/lib/validators/yachts';
-
-export const getHandler: RouteHandler = async (req, ctx, params) => {
-  try {
-    const yacht = await getYachtById(params.id!, ctx.portId);
-    return NextResponse.json({ data: yacht });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
-
-export const patchHandler: RouteHandler = async (req, ctx, params) => {
-  try {
-    const body = await parseBody(req, updateYachtSchema);
-    const updated = await updateYacht(params.id!, ctx.portId, body, {
-      userId: ctx.userId,
-      portId: ctx.portId,
-      ipAddress: ctx.ipAddress,
-      userAgent: ctx.userAgent,
-    });
-    return NextResponse.json({ data: updated });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
-
-export const deleteHandler: RouteHandler = async (req, ctx, params) => {
-  try {
-    await archiveYacht(params.id!, ctx.portId, {
-      userId: ctx.userId,
-      portId: ctx.portId,
-      ipAddress: ctx.ipAddress,
-      userAgent: ctx.userAgent,
-    });
-    return new NextResponse(null, { status: 204 });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
+import { getHandler, patchHandler, deleteHandler } from './handlers';
 
 export const GET = withAuth(withPermission('yachts', 'view', getHandler));
 export const PATCH = withAuth(withPermission('yachts', 'edit', patchHandler));

src/app/api/v1/yachts/[id]/tags/route.ts

@@ -0,0 +1,28 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { setYachtTags } from '@/lib/services/yachts.service';
+
+const setTagsSchema = z.object({
+  tagIds: z.array(z.string()),
+});
+
+export const PUT = withAuth(
+  withPermission('yachts', 'edit', async (req, ctx, params) => {
+    try {
+      const { tagIds } = await parseBody(req, setTagsSchema);
+      await setYachtTags(params.id!, ctx.portId, tagIds, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ success: true });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/yachts/handlers.ts

@@ -0,0 +1,44 @@
+import { NextResponse } from 'next/server';
+
+import { type RouteHandler } from '@/lib/api/helpers';
+import { parseQuery, parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { listYachts, createYacht } from '@/lib/services/yachts.service';
+import { listYachtsSchema, createYachtSchema } from '@/lib/validators/yachts';
+
+export const listHandler: RouteHandler = async (req, ctx) => {
+  try {
+    const query = parseQuery(req, listYachtsSchema);
+    const result = await listYachts(ctx.portId, query);
+    const { page, limit } = query;
+    const totalPages = Math.ceil(result.total / limit);
+    return NextResponse.json({
+      data: result.data,
+      pagination: {
+        page,
+        pageSize: limit,
+        total: result.total,
+        totalPages,
+        hasNextPage: page < totalPages,
+        hasPreviousPage: page > 1,
+      },
+    });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};
+
+export const createHandler: RouteHandler = async (req, ctx) => {
+  try {
+    const body = await parseBody(req, createYachtSchema);
+    const yacht = await createYacht(ctx.portId, body, {
+      userId: ctx.userId,
+      portId: ctx.portId,
+      ipAddress: ctx.ipAddress,
+      userAgent: ctx.userAgent,
+    });
+    return NextResponse.json({ data: yacht }, { status: 201 });
+  } catch (error) {
+    return errorResponse(error);
+  }
+};

src/app/api/v1/yachts/route.ts

@@ -1,47 +1,6 @@
-import { NextResponse } from 'next/server';
+import { withAuth, withPermission } from '@/lib/api/helpers';
 
-import { withAuth, withPermission, type RouteHandler } from '@/lib/api/helpers';
-import { parseQuery, parseBody } from '@/lib/api/route-helpers';
-import { errorResponse } from '@/lib/errors';
-import { listYachts, createYacht } from '@/lib/services/yachts.service';
-import { listYachtsSchema, createYachtSchema } from '@/lib/validators/yachts';
-
-export const listHandler: RouteHandler = async (req, ctx) => {
-  try {
-    const query = parseQuery(req, listYachtsSchema);
-    const result = await listYachts(ctx.portId, query);
-    const { page, limit } = query;
-    const totalPages = Math.ceil(result.total / limit);
-    return NextResponse.json({
-      data: result.data,
-      pagination: {
-        page,
-        pageSize: limit,
-        total: result.total,
-        totalPages,
-        hasNextPage: page < totalPages,
-        hasPreviousPage: page > 1,
-      },
-    });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
-
-export const createHandler: RouteHandler = async (req, ctx) => {
-  try {
-    const body = await parseBody(req, createYachtSchema);
-    const yacht = await createYacht(ctx.portId, body, {
-      userId: ctx.userId,
-      portId: ctx.portId,
-      ipAddress: ctx.ipAddress,
-      userAgent: ctx.userAgent,
-    });
-    return NextResponse.json({ data: yacht }, { status: 201 });
-  } catch (error) {
-    return errorResponse(error);
-  }
-};
+import { listHandler, createHandler } from './handlers';
 
 export const GET = withAuth(withPermission('yachts', 'view', listHandler));
 export const POST = withAuth(withPermission('yachts', 'create', createHandler));