docs(better-auth): extract architecture docs to separate file

Move "Architecture: Why Custom Controllers?" section from README.md
to dedicated ARCHITECTURE.md file for better documentation structure.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: kaihaase

src/core/modules/better-auth/ARCHITECTURE.md

@@ -0,0 +1,102 @@
+# Architecture: Why Custom Controllers?
+
+The `CoreBetterAuthController` implements custom endpoints instead of directly using native Better-Auth endpoints. This is **necessary** for the nest-server hybrid auth system.
+
+## 1. Hybrid-Auth-System (Legacy + Better-Auth)
+
+The nest-server supports bidirectional authentication:
+- **Legacy Auth → Better-Auth**: Users created via Legacy Auth can sign in via Better-Auth
+- **Better-Auth → Legacy Auth**: Users created via Better-Auth can sign in via Legacy Auth
+
+This requires custom logic that cannot be implemented via Better-Auth hooks alone.
+
+## 2. Why Not Better-Auth Hooks?
+
+Better-Auth hooks have fundamental limitations that prevent full implementation of our requirements:
+
+| Requirement | Hook Support | Reason |
+|-------------|--------------|--------|
+| Legacy user migration | ⚠️ Partial | Requires global DB access outside NestJS DI |
+| Password sync to Legacy | ❌ No | **After-hooks don't have access to plaintext password** |
+| Custom response format | ❌ No | **Hooks cannot modify HTTP response** |
+| Multi-cookie setting | ❌ No | **Hooks cannot set cookies** |
+| User mapping with roles | ❌ No | Requires NestJS Dependency Injection |
+| Session token injection | ❌ No | Before-hooks cannot inject tokens into requests |
+
+## 3. Hook Limitations Explained
+
+### After-Hooks Cannot Change Response
+
+```typescript
+// ❌ This does NOT work - return value is ignored
+hooks: {
+  after: createAuthMiddleware(async (ctx) => {
+    ctx.response.body.customField = 'value'; // Ignored!
+    return { response: modifiedResponse }; // Also ignored!
+  }),
+}
+```
+
+### After-Hooks Don't Have Plaintext Password
+
+```typescript
+// ❌ Cannot sync password because it's already hashed
+hooks: {
+  after: [
+    {
+      matcher: (ctx) => ctx.path === '/sign-up/email',
+      handler: async (ctx) => {
+        // ctx.body.password is ALREADY HASHED at this point
+        // We cannot call syncPasswordToLegacy() without plaintext!
+      },
+    },
+  ],
+}
+```
+
+### Hooks Don't Have NestJS DI Access
+
+```typescript
+// ❌ Hooks are configured in betterAuth(), not in NestJS context
+export const auth = betterAuth({
+  hooks: {
+    // No access to NestJS services here!
+    // this.userService, this.emailService, etc. are unavailable
+  },
+});
+```
+
+## 4. What Custom Endpoints Do
+
+| Endpoint | Custom Logic | Why Required |
+|----------|--------------|--------------|
+| `/sign-in/email` | Legacy migration, PW normalization, 2FA handling | Migration needs plaintext password |
+| `/sign-up/email` | PW normalization, Legacy sync, User linking | Sync needs plaintext password |
+| `/sign-out` | Multi-cookie clearing | Response modification |
+| `/session` | User mapping with roles | NestJS service access |
+| Plugin routes | Session token injection | Request modification |
+
+## 5. Native Handler Where Possible
+
+Despite custom endpoints, we use Better-Auth's native handler where appropriate:
+- **Plugin routes** (Passkey, 2FA, OAuth) → `authInstance.handler()`
+- **2FA verification flow** → Native handler for correct cookie setting
+- **Passkey authentication** → Native WebAuthn handling
+
+## 6. Alternative Approaches Considered
+
+| Approach | Evaluation |
+|----------|------------|
+| **Full Hook Approach** | ❌ Not feasible - missing plaintext password, no response modification |
+| **Hybrid with Global DB** | ⚠️ Possible but anti-pattern - bypasses NestJS DI, harder to test |
+| **Custom Controller (current)** | ✅ Best balance - NestJS DI access, testable, maintainable |
+
+## Conclusion
+
+The custom controller architecture is **necessary complexity**, not unnecessary overhead. It enables:
+- ✅ Legacy Auth compatibility
+- ✅ Bidirectional password synchronization
+- ✅ Multi-cookie support
+- ✅ Custom user mapping with roles
+- ✅ Proper 2FA cookie handling
+- ✅ Full NestJS Dependency Injection access

src/core/modules/better-auth/INTEGRATION-CHECKLIST.md

@@ -439,6 +439,84 @@ async function deletePasskey(passkeyId: string) {
 
 ---
 
+## Better-Auth Hooks: Limitations & Warnings
+
+### Why nest-server Uses Custom Controllers
+
+nest-server implements custom REST endpoints instead of relying solely on Better-Auth hooks. This is **by design** due to fundamental hook limitations.
+
+### Hook Limitations Summary
+
+| Limitation | Impact |
+|------------|--------|
+| **After-hooks cannot access plaintext password** | Cannot sync password to Legacy Auth after sign-up |
+| **Hooks cannot modify HTTP response** | Cannot customize response format or add custom fields |
+| **Hooks cannot set cookies** | Cannot implement multi-cookie auth strategy |
+| **No NestJS Dependency Injection** | Cannot access services like UserService, EmailService |
+| **Before-hooks cannot inject tokens** | Cannot add session tokens to request headers |
+
+### What You CAN Do with Hooks
+
+Better-Auth hooks are suitable for:
+- ✅ Logging and analytics (side effects only)
+- ✅ Sending notifications after events
+- ✅ Simple validation in before-hooks
+- ✅ Database writes using global connection (not recommended)
+
+### What You CANNOT Do with Hooks
+
+Do NOT try to implement these via hooks:
+- ❌ Password synchronization between auth systems
+- ❌ Custom response formats
+- ❌ Setting authentication cookies
+- ❌ User role mapping
+- ❌ Legacy auth migration
+
+### Recommended Approach
+
+If you need custom authentication logic:
+
+1. **Extend the Controller** - Override methods in `BetterAuthController`
+2. **Use NestJS Services** - Inject services via constructor
+3. **Call super()** - Reuse base implementation where possible
+
+```typescript
+// Correct: Custom logic via controller extension
+@Controller('iam')
+export class BetterAuthController extends CoreBetterAuthController {
+  constructor(
+    betterAuthService: CoreBetterAuthService,
+    userMapper: CoreBetterAuthUserMapper,
+    configService: ConfigService,
+    private readonly analyticsService: AnalyticsService, // Custom service
+  ) {
+    super(betterAuthService, userMapper, configService);
+  }
+
+  @Post('sign-up/email')
+  @Roles(RoleEnum.S_EVERYONE)
+  override async signUp(
+    @Res({ passthrough: true }) res: Response,
+    @Body() input: CoreBetterAuthSignUpInput,
+  ): Promise<CoreBetterAuthResponse> {
+    const result = await super.signUp(res, input);
+
+    // Custom logic with full NestJS DI access
+    if (result.success) {
+      await this.analyticsService.trackSignUp(result.user.id);
+    }
+
+    return result;
+  }
+}
+```
+
+### Further Reading
+
+See README.md section "Architecture: Why Custom Controllers?" for detailed explanation.
+
+---
+
 ## Detailed Documentation
 
 For complete configuration options, API reference, and advanced topics:

src/core/modules/better-auth/README.md

@@ -1570,6 +1570,12 @@ describe('My Tests', () => {
 });
 ```
 
+## Architecture: Why Custom Controllers?
+
+See **[ARCHITECTURE.md](./ARCHITECTURE.md)** for detailed documentation on why custom controllers are necessary for the hybrid auth system.
+
+---
+
 ## Troubleshooting
 
 ### Better-Auth endpoints return 404

src/core/modules/better-auth/core-better-auth.controller.ts

@@ -126,6 +126,32 @@ export class CoreBetterAuthSignUpInput {
  * This controller follows the same pattern as CoreAuthController and can be
  * extended by project-specific implementations.
  *
+ * ## Why Custom Controller Instead of Native Better-Auth Endpoints?
+ *
+ * This controller implements custom endpoints rather than directly using Better-Auth's
+ * native API. This architecture is **necessary** for nest-server's requirements:
+ *
+ * ### 1. Better-Auth Hooks Cannot:
+ * - Access plaintext passwords in after-hooks (needed for Legacy sync)
+ * - Modify HTTP responses (needed for custom response format)
+ * - Set cookies (needed for multi-cookie auth strategy)
+ * - Access NestJS Dependency Injection (needed for UserService, etc.)
+ *
+ * ### 2. Custom Endpoints Enable:
+ * - **Hybrid Auth**: Bidirectional Legacy Auth ↔ Better-Auth synchronization
+ * - **Password Normalization**: SHA256 pre-hashing for security
+ * - **Legacy Migration**: Automatic migration of legacy users on sign-in
+ * - **Multi-Cookie Support**: Setting multiple auth cookies for compatibility
+ * - **Role Mapping**: Integration with nest-server's role-based access control
+ *
+ * ### 3. Native Handler Where Possible:
+ * Despite custom endpoints, we use `authInstance.handler()` for:
+ * - Plugin routes (Passkey, 2FA, OAuth)
+ * - 2FA verification (for correct cookie handling)
+ * - All plugin-provided functionality
+ *
+ * See README.md section "Architecture: Why Custom Controllers?" for details.
+ *
  * @example
  * ```typescript
  * // In your project - src/server/modules/better-auth/better-auth.controller.ts
@@ -169,14 +195,22 @@ export class CoreBetterAuthController {
   /**
    * Sign in with email and password
    *
-   * This endpoint handles legacy user migration and password normalization.
+   * **Why Custom Implementation (not hooks):**
+   * - Hooks cannot access plaintext password for legacy migration
+   * - Hooks cannot modify response format
+   * - Hooks cannot set multi-cookie auth strategy
    *
-   * Flow:
+   * **Flow:**
    * 1. Try legacy user migration if the user exists in legacy system
-   * 2. Normalize password to SHA256 format
+   *    → Requires plaintext password (unavailable in after-hooks)
+   * 2. Normalize password to SHA256 format for Better Auth
    * 3. Call Better Auth API directly for consistent response format
    * 4. For 2FA: Use native handler to ensure cookies are set correctly
-   * 5. Return response with session cookies
+   *    → Hooks cannot set cookies, so we use authInstance.handler()
+   * 5. Return response with multiple auth cookies
+   *    → Hooks cannot modify response or set cookies
+   *
+   * @see README.md "Architecture: Why Custom Controllers?"
    */
   @ApiBody({ type: CoreBetterAuthSignInInput })
   @ApiCreatedResponse({ description: 'Signed in successfully', type: CoreBetterAuthResponse })
@@ -317,6 +351,23 @@ export class CoreBetterAuthController {
 
   /**
    * Sign up with email and password
+   *
+   * **Why Custom Implementation (not hooks):**
+   * - After-hooks don't have access to plaintext password
+   *   → Cannot call syncPasswordToLegacy() in hooks
+   * - Hooks cannot access NestJS services
+   *   → Cannot use UserMapper for user linking
+   * - Hooks cannot modify response format
+   *
+   * **Custom Logic:**
+   * 1. Normalize password to SHA256 for Better Auth storage
+   * 2. Create user via Better Auth API
+   * 3. Link user to Legacy system (requires NestJS UserMapper)
+   * 4. Sync plaintext password to Legacy Auth (bcrypt hash)
+   *    → CRITICAL: This requires plaintext, unavailable in after-hooks
+   * 5. Return response with session cookies
+   *
+   * @see README.md "Architecture: Why Custom Controllers?"
    */
   @ApiBody({ type: CoreBetterAuthSignUpInput })
   @ApiCreatedResponse({ description: 'Signed up successfully', type: CoreBetterAuthResponse })
@@ -384,7 +435,13 @@ export class CoreBetterAuthController {
   /**
    * Sign out (logout)
    *
+   * **Why Custom Implementation (not hooks):**
+   * - Must clear multiple cookies (token, session, better-auth.session_token, etc.)
+   * - Hooks cannot modify response or set/clear cookies
+   *
    * NOTE: Better-Auth uses POST for sign-out (matches better-auth convention)
+   *
+   * @see README.md "Architecture: Why Custom Controllers?"
    */
   @ApiOkResponse({ description: 'Signed out successfully', type: CoreBetterAuthResponse })
   @ApiOperation({ description: 'Sign out from Better-Auth', summary: 'Sign Out' })
@@ -417,6 +474,13 @@ export class CoreBetterAuthController {
 
   /**
    * Get current session
+   *
+   * **Why Custom Implementation (not hooks):**
+   * - Must map Better Auth user to nest-server user with roles
+   * - Hooks cannot access NestJS UserMapper service
+   * - Custom response format with mapped user data
+   *
+   * @see README.md "Architecture: Why Custom Controllers?"
    */
   @ApiOkResponse({ description: 'Current session', type: CoreBetterAuthResponse })
   @ApiOperation({ description: 'Get current session from Better-Auth', summary: 'Get Session' })
@@ -454,7 +518,17 @@ export class CoreBetterAuthController {
   /**
    * Catch-all route for all other Better Auth plugin endpoints.
    *
-   * This route handles:
+   * **This route USES the native Better Auth handler** via `authInstance.handler()`.
+   * It's the best of both worlds:
+   * - Custom endpoints where we need NestJS features (sign-in, sign-up, etc.)
+   * - Native handler for plugins that work correctly out-of-the-box
+   *
+   * **Why Not Fully Native:**
+   * Even this catch-all requires custom logic:
+   * - Session token injection into request (before-hooks can't inject tokens)
+   * - Converting Express Request to Web Standard Request
+   *
+   * **Handles:**
    * - Passkey/WebAuthn (all endpoints)
    * - Two-Factor Authentication (all endpoints)
    * - Social Login OAuth flows
@@ -467,6 +541,8 @@ export class CoreBetterAuthController {
    *
    * Better Auth handles authentication internally - it returns appropriate
    * errors (401, 403) if a user is not authenticated for protected endpoints.
+   *
+   * @see README.md "Architecture: Why Custom Controllers?"
    */
   @All('*path')
   @Roles(RoleEnum.S_EVERYONE)