IMPLEMENTATION_PHASES.md

Architecture Migration – Implementation Phases

This document tracks the concrete implementation phases for migrating Impactify from Supabase Auth + Supabase Postgres/Storage to Better Auth, generic Postgres (local via Docker), Cloudflare R2, and Prisma as the schema brain.

---

Phase 0 – Discovery & Guardrails (done)

• Goals
  • Freeze current architecture in docs (ARCHITECTURE.md, PROJECT_OVERVIEW.md, current-db-schema.md).
  • Decide target stack: Better Auth + generic Postgres (local via Docker, managed later), Cloudflare R2, Prisma as schema brain.
• Exit criteria
  • Written plan (migrate-to-better-auth-and-local-postgres).
  • Clear decision that Supabase Auth is being replaced and Supabase DB/Storage are legacy.

---

Phase 1 – Local Postgres & Migrations

• Goals
  • Run the existing app against local Postgres in Docker for development.
• Key tasks
  • Use docker-compose.postgres.yml to run a local Postgres (impactify DB/user/password, port 5432).
  • Point impactis-server/.env.local DATABASE_URL at the Docker Postgres.
  • Add a script (e.g. npm run db:migrate:local) to apply all supabase/migrations/*.sql to local Postgres.
  • Smoke test: run impactis-server + impactis-client on local Postgres; workspace, billing, and data room work end-to-end.
• Exit criteria
  • One command to bring up DB and another to apply migrations.
  • Local dev no longer depends on Supabase Postgres.

---

Phase 2 – Better Auth Integration (Minimal Vertical Slice, done)

• Goals
  • Switch authentication from Supabase Auth to Better Auth for all workspace flows.
• Key tasks
  • Client (impactis-client)
    • Better Auth is configured and used for /auth/* pages and session management.
    • /api/auth/* routes are handled by Better Auth.
    • Workspace/server actions call NestJS using the Better Auth token (via getBetterAuthToken and Authorization: Bearer header).
    • Security → Active Sessions page lists Better Auth sessions and can revoke specific sessions or all other sessions using authClient.listSessions, revokeSession, and revokeOtherSessions.
  • Server (impactis-server)
    • Auth integration validates Better Auth JWTs using JWKS (BETTER_AUTH_JWKS_URL) and issuer (BETTER_AUTH_ISSUER).
    • All workspace/billing/startups/organizations/profile controllers use the Better Auth–backed guard; there is no SupabaseJwtGuard.
    • Legacy Supabase-based auth.sessions querying in SessionsService has been disabled; NestJS no longer depends on Supabase Auth tables.
  • Env cleanup
    • Supabase auth envs are no longer required by the NestJS codebase.
    • Better Auth envs (BETTER_AUTH_JWKS_URL, BETTER_AUTH_ISSUER) are documented and used.
• Exit criteria
  • Users sign up / sign in via Better Auth and use workspace, billing, and data room in dev.
  • Supabase Auth is not needed to run the stack locally.

---

Phase 3 – Prisma Schema Alignment

• Goals
  • Use Prisma as the structured representation of the schema while keeping SQL migrations as the DDL source of truth.
• Key tasks
  • Add schema.prisma under impactis-server and pull the schema from local Postgres as a starting point.
  • Hand-align schema.prisma with docs/current-db-schema.md (tables, relations, enums).
  • Generate Prisma Client and integrate it with PrismaService:
    • Start using Prisma Client for straightforward queries (e.g. profiles, organizations).
    • Keep raw SQL for complex views and reporting.
  • Update docs/current-db-schema.md to mention schema.prisma as the code-side mirror of the DB schema.
• Exit criteria
  • schema.prisma and current-db-schema.md describe the same schema.
  • Prisma Client is used in at least one module without regressions.

---

Phase 4 – Storage Migration to Cloudflare R2 (in progress)

• Goals
  • Move uploads (avatars, logos, data room docs) from legacy Supabase-style URLs to Cloudflare R2, preserving existing data where needed.
• Key tasks
  • Backend
    • FilesModule R2 integration is active with signed upload URL endpoints for:
      • Startup data room documents.
      • Organization logos.
      • Profile avatars.
    • Ensure DB continues to use storage_bucket and storage_object_path consistently, with new R2 bucket names (e.g. startup-data-room-assets).
  • Frontend
    • Upload actions:
      • Request signed URL from NestJS.
      • PUT file bytes directly to R2.
      • Persist file metadata via existing APIs (startup_data_room_documents, profiles, organizations).
    • Existing legacy URLs already stored in file_url can still be rendered; new uploads use the R2 URL shape end-to-end.
  • Docs
    • ARCHITECTURE.md “File flows” shows R2 as the primary storage backend.
    • PROJECT_OVERVIEW.md documents that avatars, logos, and data-room docs now use R2 via signed URLs.
• Exit criteria
  • New uploads use R2 in dev.
  • Data room, logos, and avatars work end-to-end with R2.

---

Phase 5 – Cleanup & Hardening (ongoing)

• Goals
  • Remove remaining Supabase-specific coupling and lock in the new stack (Better Auth + NestJS + generic Postgres + R2).
• Key tasks
  • Confirm there is no Supabase SDK or Supabase auth usage in client or server code.
  • Keep only legacy URL parsing where needed to read old Supabase-style file_url values; new uploads must not depend on Supabase.
  • Maintain a concise “Local Dev & Deployment” section in ARCHITECTURE.md that explains:
    • How to run DB, migrations, server, and client.
    • How Better Auth, Postgres, Prisma, and R2 fit together.
  • Document and enforce capability-based feature gates, especially:
    • dataroom.upload and dataroom.manage for startup data-room docs.
    • data_room_documents_limit plan feature for per-org document limits.
• Exit criteria
  • No code paths require Supabase Auth or Supabase-specific env vars to run the app.
  • New contributors can follow the docs to spin up the full stack locally using Docker Postgres, Better Auth, Prisma, and R2.