refactor: fix biome linting issues and update project documentation

- Fix 36+ biome linting issues reducing errors/warnings from 227 to 191
- Replace explicit 'any' types with proper TypeScript interfaces
- Fix React hooks dependencies and useCallback patterns
- Resolve unused variables and parameter assignment issues
- Improve accessibility with proper label associations
- Add comprehensive API documentation for admin and security features
- Update README.md with accurate PostgreSQL setup and current tech stack
- Create complete documentation for audit logging, CSP monitoring, and batch processing
- Fix outdated project information and missing developer workflows

app/api/platform/companies/[id]/users/route.ts

@@ -73,14 +73,13 @@ export async function POST(
           { error: "User already exists in this company" },
           { status: 400 }
         );
-      } else {
-        return NextResponse.json(
-          {
-            error: `Email already in use by a user in company: ${existingUser.company.name}. Each email address can only be used once across all companies.`
-          },
-          { status: 400 }
-        );
       }
+      return NextResponse.json(
+        {
+          error: `Email already in use by a user in company: ${existingUser.company.name}. Each email address can only be used once across all companies.`,
+        },
+        { status: 400 }
+      );
     }
 
     // Generate a temporary password (in a real app, you'd send an invitation email)

app/api/platform/companies/route.ts

@@ -3,13 +3,34 @@ import { type NextRequest, NextResponse } from "next/server";
 import { getServerSession } from "next-auth";
 import { platformAuthOptions } from "../../../../lib/platform-auth";
 import { prisma } from "../../../../lib/prisma";
+import { extractClientIP } from "../../../../lib/rateLimiter";
+import {
+  AuditOutcome,
+  createAuditMetadata,
+  securityAuditLogger,
+} from "../../../../lib/securityAuditLogger";
 
 // GET /api/platform/companies - List all companies
 export async function GET(request: NextRequest) {
   try {
     const session = await getServerSession(platformAuthOptions);
+    const ip = extractClientIP(request);
+    const userAgent = request.headers.get("user-agent") || undefined;
 
     if (!session?.user?.isPlatformUser) {
+      await securityAuditLogger.logPlatformAdmin(
+        "platform_companies_unauthorized_access",
+        AuditOutcome.BLOCKED,
+        {
+          ipAddress: ip,
+          userAgent,
+          metadata: createAuditMetadata({
+            error: "no_platform_session",
+          }),
+        },
+        "Unauthorized attempt to access platform companies list"
+      );
+
       return NextResponse.json(
         { error: "Platform access required" },
         { status: 401 }
@@ -63,6 +84,24 @@ export async function GET(request: NextRequest) {
       prisma.company.count({ where }),
     ]);
 
+    // Log successful platform companies access
+    await securityAuditLogger.logPlatformAdmin(
+      "platform_companies_list_accessed",
+      AuditOutcome.SUCCESS,
+      {
+        platformUserId: session.user.id,
+        ipAddress: ip,
+        userAgent,
+        metadata: createAuditMetadata({
+          companiesReturned: companies.length,
+          totalCompanies: total,
+          filters: { status, search },
+          pagination: { page, limit },
+        }),
+      },
+      "Platform companies list accessed"
+    );
+
     return NextResponse.json({
       companies,
       pagination: {
@@ -74,6 +113,21 @@ export async function GET(request: NextRequest) {
     });
   } catch (error) {
     console.error("Platform companies list error:", error);
+
+    await securityAuditLogger.logPlatformAdmin(
+      "platform_companies_list_error",
+      AuditOutcome.FAILURE,
+      {
+        platformUserId: session?.user?.id,
+        ipAddress: extractClientIP(request),
+        userAgent: request.headers.get("user-agent") || undefined,
+        metadata: createAuditMetadata({
+          error: "server_error",
+        }),
+      },
+      `Server error in platform companies list: ${error}`
+    );
+
     return NextResponse.json(
       { error: "Internal server error" },
       { status: 500 }
@@ -85,11 +139,29 @@ export async function GET(request: NextRequest) {
 export async function POST(request: NextRequest) {
   try {
     const session = await getServerSession(platformAuthOptions);
+    const ip = extractClientIP(request);
+    const userAgent = request.headers.get("user-agent") || undefined;
 
     if (
       !session?.user?.isPlatformUser ||
       session.user.platformRole === "SUPPORT"
     ) {
+      await securityAuditLogger.logPlatformAdmin(
+        "platform_company_create_unauthorized",
+        AuditOutcome.BLOCKED,
+        {
+          platformUserId: session?.user?.id,
+          ipAddress: ip,
+          userAgent,
+          metadata: createAuditMetadata({
+            error: "insufficient_permissions",
+            requiredRole: "ADMIN",
+            currentRole: session?.user?.platformRole,
+          }),
+        },
+        "Unauthorized attempt to create platform company"
+      );
+
       return NextResponse.json(
         { error: "Admin access required" },
         { status: 403 }
@@ -165,6 +237,27 @@ export async function POST(request: NextRequest) {
       };
     });
 
+    // Log successful company creation
+    await securityAuditLogger.logCompanyManagement(
+      "platform_company_created",
+      AuditOutcome.SUCCESS,
+      {
+        platformUserId: session.user.id,
+        companyId: result.company.id,
+        ipAddress: ip,
+        userAgent,
+        metadata: createAuditMetadata({
+          companyName: result.company.name,
+          companyStatus: result.company.status,
+          adminUserEmail: "[REDACTED]",
+          adminUserName: result.adminUser.name,
+          maxUsers: result.company.maxUsers,
+          hasGeneratedPassword: !!result.generatedPassword,
+        }),
+      },
+      "Platform company created successfully"
+    );
+
     return NextResponse.json(
       {
         company: result.company,
@@ -179,6 +272,21 @@ export async function POST(request: NextRequest) {
     );
   } catch (error) {
     console.error("Platform company creation error:", error);
+
+    await securityAuditLogger.logCompanyManagement(
+      "platform_company_create_error",
+      AuditOutcome.FAILURE,
+      {
+        platformUserId: session?.user?.id,
+        ipAddress: extractClientIP(request),
+        userAgent: request.headers.get("user-agent") || undefined,
+        metadata: createAuditMetadata({
+          error: "server_error",
+        }),
+      },
+      `Server error in platform company creation: ${error}`
+    );
+
     return NextResponse.json(
       { error: "Internal server error" },
       { status: 500 }