Skip to content

REFACTORING-PLAN.md

Latest commit

 

History

History
239 lines (188 loc) · 5.48 KB

REFACTORING-PLAN.md

File metadata and controls

239 lines (188 loc) · 5.48 KB
Raw

COMPREHENSIVE REFACTORING & FIX PLAN

October 4, 2025

ISSUE 1: REMOVE UNNECESSARY FILES ✅

Files to Delete (Do NOT affect functionality):

Documentation/Archive Files:

  • apps/VERCEL-DEPLOYMENT-FIXED.md
  • apps/VERCEL-DEPLOYMENT-GUIDE.md
  • apps/web/DEPLOYMENT-SUCCESS-GUIDE.md
  • apps/web/REACT-ROUTER-CONVERSION-PLAN.md
  • apps/web/VERCEL-CRITICAL-CHECKS.md
  • apps/web/SPA-BUILD-FIX.md
  • 404-FIX-GUIDE.md
  • COMPLETE-FIX-SUMMARY.md
  • apps/docs-archive/* (entire directory)
  • apps/web/docs-archive/* (entire directory)

Unused/Duplicate Files:

  • apps/web/api/index.js (attempts SSR wrapper - not needed)
  • apps/web/api/server.js (fallback HTML server - not needed with proper SPA)
  • apps/web/server.js (SSR server - not needed in SPA mode)
  • apps/web/deployment-config.js
  • apps/web/deploy-check.ps1
  • apps/web/deploy-check.sh
  • apps/web/vite.config.static.ts (if exists - we use vite.config.ts)
  • apps/web/build/client/deployment-test.html

Root Level Duplicates:

  • vercel.json (root) - We only need apps/web/vercel.json

Total Cleanup: ~20+ unnecessary files

ISSUE 2: BLANK WHITE SCREEN FIX 🎯

ROOT CAUSE:

The entry.client.tsx is using HydratedRouter which expects SSR pre-rendered HTML, but we're in SPA mode with ssr: false.

SOLUTION:

File: apps/web/src/app/entry.client.tsx

Current (BROKEN):

import { createRoot } from "react-dom/client";
import { HydratedRouter } from "react-router/dom";

const rootElement = document.getElementById("root");
if (rootElement) {
  createRoot(rootElement).render(
    <StrictMode>
      <HydratedRouter />  // ❌ WRONG - expects SSR
    </StrictMode>
  );
}

Fixed (CORRECT):

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { RouterProvider, createBrowserRouter } from "react-router-dom";
import { routes } from "./routes";  // Import your routes
import Root, { Layout } from "./root";

// Create browser router for SPA
const router = createBrowserRouter([
  {
    path: "/",
    element: <Layout><Root /></Layout>,
    children: routes, // Your route configuration
  },
]);

const rootElement = document.getElementById("root");
if (rootElement) {
  createRoot(rootElement).render(
    <StrictMode>
      <RouterProvider router={router} />  // ✅ CORRECT - SPA routing
    </StrictMode>
  );
}

Alternative Simpler Fix (if routes auto-detected):

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { BrowserRouter } from "react-router-dom";
import App from "./root";

const rootElement = document.getElementById("root");
if (rootElement) {
  createRoot(rootElement).render(
    <StrictMode>
      <BrowserRouter>
        <App />
      </BrowserRouter>
    </StrictMode>
  );
}

ISSUE 3: DATABASE ACCESS FROM NEON DB 🗄️

DIAGNOSIS STEPS:

Step 1: Verify Environment Variable

Check Vercel Dashboard → monastery360 → Settings → Environment Variables

Required:

Name: DATABASE_URL
Value: postgresql://[user]:[password]@[host]/[database]?sslmode=require
Scope: Production, Preview, Development

Step 2: Test Health Endpoint

curl https://monastery360-6s3patpb2-0xasr.vercel.app/api/health

Expected Success:

{
  "status": "healthy",
  "checks": {
    "databaseUrl": true,
    "databaseConnection": true,
    "tablesAccessible": true
  }
}

If Failure:

{
  "error": "Database configuration error - DATABASE_URL not set"
}

Step 3: Common Issues & Fixes

Issue 3.1: Environment Variable Not Set

  • Go to Vercel Dashboard
  • Add DATABASE_URL
  • Redeploy

Issue 3.2: Connection String Format Wrong Correct format:

postgresql://username:password@host:5432/database?sslmode=require

For Neon:

postgresql://[user]:[password]@[ep-xxx-xxx].us-east-2.aws.neon.tech/[dbname]?sslmode=require

Issue 3.3: Neon Database Not Accepting Connections

  • Check Neon dashboard: Project is active
  • Check Neon compute: Auto-suspend disabled OR compute is running
  • Verify IP allowlist (Vercel IPs allowed)

Issue 3.4: SSL/TLS Issues Add to connection string:

?sslmode=require&sslrootcert=DISABLE_SSL_VERIFY

Issue 3.5: Pool Connection Limits Neon Free Tier: 100 concurrent connections Check if limit reached

IMPLEMENTATION ORDER:

Phase 1: Fix Blank Screen (PRIORITY 1)

  1. Update entry.client.tsx to use BrowserRouter
  2. Test locally: npm run dev
  3. Build: npm run build
  4. Deploy: vercel --prod

Phase 2: Verify Database (PRIORITY 2)

  1. Check Vercel env vars
  2. Test /api/health
  3. Fix connection string if needed
  4. Test /api/monasteries

Phase 3: Cleanup (PRIORITY 3)

  1. Delete unnecessary docs
  2. Delete unused API files
  3. Delete deployment scripts
  4. Clean build artifacts

DETAILED FIX FILES:

Fix 1: entry.client.tsx (CRITICAL)

Fix 2: Verify/Add DATABASE_URL in Vercel

Fix 3: Delete unnecessary files

TESTING CHECKLIST:

  • Local dev works: npm run dev
  • Build succeeds: npm run build
  • Deploy succeeds: vercel --prod
  • Main URL loads (not blank)
  • /api/health returns success
  • /api/monasteries returns data
  • All routes navigate correctly
  • No console errors

ROLLBACK PLAN:

If something breaks:

  1. Git checkout previous working commit
  2. Redeploy: vercel --prod
  3. Verify APIs still work

STATUS: Ready to implement ESTIMATED TIME: 30 minutes RISK: LOW (can rollback)