BFF Compatibility Layer — Path Routing & Migration Guide

Overview

The myProp Next.js application includes a Backend-for-Frontend (BFF) compatibility layer that proxies requests to the underlying AgentOS Lambda APIs. This layer allows the Next.js app to act as a unified API gateway for all connected clients — the Vue frontend, the Capacitor mobile app, and any third-party integrations.

Current Mount Point

The BFF catch-all route handler is located at:

src/app/api/bff/[...path]/route.ts

This means all BFF routes are currently accessible only under the /api/bff/ prefix:

Original Lambda Path	Current BFF Path
POST /accounts	POST /api/bff/accounts
POST /company/verify	POST /api/bff/company/verify
POST /messaging/messages	POST /api/bff/messaging/messages

⚠️ Known Incompatibility with Existing Clients

The original Vue app and Capacitor mobile app call API endpoints using the unprefixed Lambda paths (e.g. POST /accounts) — without any /api/bff/ prefix. Because the middleware at src/middleware.ts only marks /api/bff/* paths as public, requests to the original paths are not routed to the BFF handler and return 404 Not Found.

Affected Clients

• Vue frontend application
• Capacitor mobile application
• Hardcoded third-party integrations using original Lambda paths

Fixing the Path Mismatch

There are two recommended approaches to restore compatibility with existing clients.

Option A: Next.js Rewrites (Recommended)

Add URL rewrites to next.config.ts so that every original Lambda path is transparently rewritten to its /api/bff/ equivalent before routing. No client changes are required.

// next.config.ts
const nextConfig = {
  async rewrites() {
    return [
      {
        source: '/accounts/:path*',
        destination: '/api/bff/accounts/:path*',
      },
      {
        source: '/company/:path*',
        destination: '/api/bff/company/:path*',
      },
      {
        source: '/messaging/:path*',
        destination: '/api/bff/messaging/:path*',
      },
      // Repeat for every original inbound URL defined in the API spec
    ];
  },
};

export default nextConfig;

Pros:

• No changes required to any client (Vue app, mobile app, third-party integrations)
• Single source of truth for routing logic
• Cleanest long-term solution

Cons:

• Requires enumerating every original Lambda path in next.config.ts

Option B: Second Catch-All Route

Create a second Next.js API route at src/app/api/[...path]/route.ts that imports and re-exports the same handler logic as src/app/api/bff/[...path]/route.ts.

// src/app/api/[...path]/route.ts
export { GET, POST, PUT, PATCH, DELETE } from '../bff/[...path]/route';

Pros:

• Minimal code change
• Both /api/bff/* and /api/* paths work immediately

Cons:

• Two active route prefixes may cause confusion
• Does not restore the exact original unprefixed paths (e.g. /accounts still 404s without a middleware rewrite)

Middleware Configuration

The Next.js middleware at src/middleware.ts controls which routes are treated as public (unauthenticated). Ensure that any new paths — whether via rewrites or a second catch-all — are also added to the public passthrough list if they should be accessible without authentication.

// src/middleware.ts (excerpt)
// Current public passthrough — extend as needed:
// /api/bff/* → public
// /api/*     → add if using Option B

Summary

Approach	Client Changes Required	Complexity
Next.js rewrites in next.config.ts	None	Low–Medium
Second catch-all route	None	Low
Update all clients to use /api/bff/ prefix	All clients must update	High

For most deployments, Option A (Next.js rewrites) is the recommended fix as it preserves backward compatibility without modifying any client application.