feat: implement preview read-only mode with upsell guidance and error handling

.env.example

@@ -62,9 +62,14 @@ S3_FORCE_PATH_STYLE=true
 # Production: https://applirank.com
 NUXT_PUBLIC_SITE_URL=http://localhost:3000
 
+# Public URL used by preview upsell modal "Upgrade to hosted plan" button
+# NUXT_PUBLIC_HOSTED_PLAN_URL=https://applirank.com
+
 # ─── Optional: Demo Mode ────────────────────
 # Set to an org slug to make that org read-only (blocks mutations)
-# DEMO_ORG_SLUG=demo
+# Default seeded slug: applirank-demo
+# Railway PR preview seeded slug: applirank-pr-demo
+# DEMO_ORG_SLUG=applirank-demo
 
 # ─── Optional: Trusted Proxy ────────────────
 # IP address of the reverse proxy (Railway/Cloudflare). When set,

CHANGELOG.md

@@ -12,10 +12,13 @@ Format follows [Keep a Changelog](https://keepachangelog.com). Categories: **Add
 
 - **Dependency security remediation** — resolved all `npm audit --audit-level=high` findings by upgrading `@aws-sdk/client-s3` (pulling patched `@aws-sdk/xml-builder`) and regenerating lockfile resolution
 - **Transitive vulnerability pinning** — added npm `overrides` for `fast-xml-parser`, `minimatch`, `tar`, and `readdir-glob` to keep vulnerable transitive ranges out of the install graph
+- **Demo write-protection enforcement** — hardened server demo guard so `POST`/`PATCH`/`PUT`/`DELETE` requests are consistently blocked for the configured demo organization and no longer silently fail open when demo org lookup fails
+- **Dashboard preview UX** — write attempts in preview mode now trigger a dedicated upsell modal instead of only inline/API errors, while keeping action buttons visible
 
 ### Changed
 
 - **Lockfile hygiene** — refreshed dependency graph with `npm install` + `npm dedupe` to remove stale vulnerable transitive entries
+- **Demo env guidance** — `.env.example` demo slug example now matches seeded demo organization slug (`applirank-demo`) to reduce configuration drift
 
 ---
 

app/components/ApplyCandidateModal.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { Search, X, UserPlus } from 'lucide-vue-next'
+import { usePreviewReadOnly } from '~/composables/usePreviewReadOnly'
 
 const props = defineProps<{
   jobId: string
@@ -32,6 +33,7 @@ const { data: candidateData, status: searchStatus } = useFetch('/api/candidates'
 })
 
 const candidates = computed(() => candidateData.value?.data ?? [])
+const { handlePreviewReadOnlyError } = usePreviewReadOnly()
 
 // Apply candidate
 const isApplying = ref(false)
@@ -47,6 +49,7 @@ async function applyCandidate(candidateId: string) {
     })
     emit('created')
   } catch (err: any) {
+    if (handlePreviewReadOnlyError(err)) return
     applyError.value = err.data?.statusMessage ?? 'Failed to apply candidate'
   } finally {
     isApplying.value = false

app/components/ApplyToJobModal.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { X, Briefcase } from 'lucide-vue-next'
+import { usePreviewReadOnly } from '~/composables/usePreviewReadOnly'
 
 const props = defineProps<{
   candidateId: string
@@ -18,6 +19,7 @@ const { data: jobData, status: jobFetchStatus } = useFetch('/api/jobs', {
 })
 
 const jobs = computed(() => jobData.value?.data ?? [])
+const { handlePreviewReadOnlyError } = usePreviewReadOnly()
 
 // Apply to job
 const isApplying = ref(false)
@@ -33,6 +35,7 @@ async function applyToJob(jobId: string) {
     })
     emit('created')
   } catch (err: any) {
+    if (handlePreviewReadOnlyError(err)) return
     applyError.value = err.data?.statusMessage ?? 'Failed to apply to job'
   } finally {
     isApplying.value = false

app/components/CandidateDetailSidebar.vue

@@ -4,6 +4,7 @@ import {
   ExternalLink, Mail, Phone, Upload, Download, Eye, Trash2,
   ArrowLeft, AlertTriangle,
 } from 'lucide-vue-next'
+import { usePreviewReadOnly } from '~/composables/usePreviewReadOnly'
 
 const props = defineProps<{
   applicationId: string
@@ -15,6 +16,8 @@ const emit = defineEmits<{
   (e: 'updated'): void
 }>()
 
+const { handlePreviewReadOnlyError } = usePreviewReadOnly()
+
 // ─────────────────────────────────────────────
 // Tabs
 // ─────────────────────────────────────────────
@@ -114,6 +117,7 @@ async function handleTransition(newStatus: string) {
     await refresh()
     emit('updated')
   } catch (err: any) {
+    if (handlePreviewReadOnlyError(err)) return
     alert(err.data?.statusMessage ?? 'Failed to update status')
   } finally {
     isTransitioning.value = false
@@ -144,6 +148,7 @@ async function saveNotes() {
     emit('updated')
     isEditingNotes.value = false
   } catch (err: any) {
+    if (handlePreviewReadOnlyError(err)) return
     alert(err.data?.statusMessage ?? 'Failed to save notes')
   } finally {
     isSavingNotes.value = false
@@ -247,6 +252,7 @@ async function handleDeleteDoc(docId: string) {
     await refreshCandidate()
     showDocDeleteConfirm.value = null
   } catch (err: any) {
+    if (handlePreviewReadOnlyError(err)) return
     alert(err.data?.statusMessage ?? 'Failed to delete document')
   } finally {
     isDeletingDoc.value = false

app/components/PreviewUpsellModal.vue

@@ -0,0 +1,69 @@
+<script setup lang="ts">
+import { Crown, X, Rocket } from 'lucide-vue-next'
+
+const emit = defineEmits<{
+  (e: 'close'): void
+}>()
+
+const { message } = usePreviewReadOnly()
+const config = useRuntimeConfig()
+
+function closeModal() {
+  emit('close')
+}
+</script>
+
+<template>
+  <Teleport to="body">
+    <div class="fixed inset-0 z-50 flex items-center justify-center p-4">
+      <div class="absolute inset-0 bg-black/50" @click="closeModal" />
+
+      <div class="relative w-full max-w-md rounded-xl border border-surface-200 bg-white shadow-xl dark:border-surface-800 dark:bg-surface-900">
+        <div class="flex items-center justify-between border-b border-surface-200 px-5 py-4 dark:border-surface-800">
+          <div class="flex items-center gap-2">
+            <Crown class="size-5 text-brand-600 dark:text-brand-400" />
+            <h3 class="text-lg font-semibold text-surface-900 dark:text-surface-50">Unlock full editing</h3>
+          </div>
+
+          <button
+            class="cursor-pointer text-surface-400 transition-colors hover:text-surface-600 dark:hover:text-surface-200"
+            @click="closeModal"
+          >
+            <X class="size-5" />
+          </button>
+        </div>
+
+        <div class="space-y-4 px-5 py-5">
+          <p class="text-sm text-surface-600 dark:text-surface-300">
+            {{ message }}
+          </p>
+
+          <p class="text-sm text-surface-500 dark:text-surface-400">
+            Want write access? Upgrade to a paid hosted plan or deploy your own Applirank instance.
+          </p>
+
+          <div class="flex flex-wrap items-center gap-2">
+            <a
+              :href="config.public.hostedPlanUrl"
+              target="_blank"
+              rel="noopener noreferrer"
+              class="inline-flex items-center gap-2 rounded-lg bg-brand-600 px-3 py-2 text-sm font-medium text-white transition-colors hover:bg-brand-700"
+            >
+              <Rocket class="size-4" />
+              Upgrade to hosted plan
+            </a>
+
+            <a
+              href="https://github.com/applirank/applirank"
+              target="_blank"
+              rel="noopener noreferrer"
+              class="inline-flex items-center rounded-lg border border-surface-300 px-3 py-2 text-sm font-medium text-surface-700 transition-colors hover:bg-surface-50 dark:border-surface-700 dark:text-surface-200 dark:hover:bg-surface-800"
+            >
+              Self-host on GitHub
+            </a>
+          </div>
+        </div>
+      </div>
+    </div>
+  </Teleport>
+</template>

app/composables/useApplication.ts

@@ -5,6 +5,7 @@ import type { MaybeRefOrGetter } from 'vue'
  * Wraps `useFetch('/api/applications/:id')` with a reactive key.
  */
 export function useApplication(id: MaybeRefOrGetter<string>) {
+  const { handlePreviewReadOnlyError } = usePreviewReadOnly()
   const applicationId = computed(() => toValue(id))
 
   const { data: application, status, error, refresh } = useFetch(
@@ -21,13 +22,18 @@ export function useApplication(id: MaybeRefOrGetter<string>) {
     notes: string | null
     score: number | null
   }>) {
-    const updated = await $fetch(`/api/applications/${applicationId.value}`, {
-      method: 'PATCH',
-      body: payload,
-    })
-    await refresh()
-    await refreshNuxtData('applications')
-    return updated
+    try {
+      const updated = await $fetch(`/api/applications/${applicationId.value}`, {
+        method: 'PATCH',
+        body: payload,
+      })
+      await refresh()
+      await refreshNuxtData('applications')
+      return updated
+    } catch (error) {
+      handlePreviewReadOnlyError(error)
+      throw error
+    }
   }
 
   return { application, status, error, refresh, updateApplication }

app/composables/useApplications.ts

@@ -1,4 +1,5 @@
 import type { Ref } from 'vue'
+import { usePreviewReadOnly } from '~/composables/usePreviewReadOnly'
 
 /**
  * Composable for managing the applications list with filtering, pagination, and mutations.
@@ -9,6 +10,8 @@ export function useApplications(options?: {
   candidateId?: Ref<string | undefined> | string
   status?: Ref<string | undefined> | string
 }) {
+  const { handlePreviewReadOnlyError } = usePreviewReadOnly()
+
   const query = computed(() => ({
     ...(toValue(options?.jobId) && { jobId: toValue(options?.jobId) }),
     ...(toValue(options?.candidateId) && { candidateId: toValue(options?.candidateId) }),
@@ -30,12 +33,17 @@ export function useApplications(options?: {
     jobId: string
     notes?: string
   }) {
-    const created = await $fetch('/api/applications', {
-      method: 'POST',
-      body: payload,
-    })
-    await refresh()
-    return created
+    try {
+      const created = await $fetch('/api/applications', {
+        method: 'POST',
+        body: payload,
+      })
+      await refresh()
+      return created
+    } catch (error) {
+      handlePreviewReadOnlyError(error)
+      throw error
+    }
   }
 
   return {

app/composables/useCandidate.ts

@@ -1,10 +1,12 @@
 import type { MaybeRefOrGetter } from 'vue'
+import { usePreviewReadOnly } from '~/composables/usePreviewReadOnly'
 
 /**
  * Composable for a single candidate detail with update and delete mutations.
  * Wraps `useFetch('/api/candidates/:id')` with a reactive key.
  */
 export function useCandidate(id: MaybeRefOrGetter<string>) {
+  const { handlePreviewReadOnlyError } = usePreviewReadOnly()
   const candidateId = computed(() => toValue(id))
 
   const { data: candidate, status, error, refresh } = useFetch(
@@ -22,18 +24,28 @@ export function useCandidate(id: MaybeRefOrGetter<string>) {
     email: string
     phone: string | null
   }>) {
-    const updated = await $fetch(`/api/candidates/${candidateId.value}`, {
-      method: 'PATCH',
-      body: payload,
-    })
-    await refresh()
-    await refreshNuxtData('candidates')
-    return updated
+    try {
+      const updated = await $fetch(`/api/candidates/${candidateId.value}`, {
+        method: 'PATCH',
+        body: payload,
+      })
+      await refresh()
+      await refreshNuxtData('candidates')
+      return updated
+    } catch (error) {
+      handlePreviewReadOnlyError(error)
+      throw error
+    }
   }
 
   /** Delete this candidate and navigate back to the list */
   async function deleteCandidate() {
-    await $fetch(`/api/candidates/${candidateId.value}`, { method: 'DELETE' })
+    try {
+      await $fetch(`/api/candidates/${candidateId.value}`, { method: 'DELETE' })
+    } catch (error) {
+      handlePreviewReadOnlyError(error)
+      throw error
+    }
     await refreshNuxtData('candidates')
     await navigateTo('/dashboard/candidates')
   }

app/composables/useCandidates.ts

@@ -1,4 +1,5 @@
 import type { Ref } from 'vue'
+import { usePreviewReadOnly } from '~/composables/usePreviewReadOnly'
 
 /**
  * Composable for managing the candidates list with search, pagination, and mutations.
@@ -7,6 +8,8 @@ import type { Ref } from 'vue'
 export function useCandidates(options?: {
   search?: Ref<string | undefined> | string
 }) {
+  const { handlePreviewReadOnlyError } = usePreviewReadOnly()
+
   const query = computed(() => ({
     ...(toValue(options?.search) && { search: toValue(options?.search) }),
   }))
@@ -27,17 +30,27 @@ export function useCandidates(options?: {
     email: string
     phone?: string
   }) {
-    const created = await $fetch('/api/candidates', {
-      method: 'POST',
-      body: payload,
-    })
-    await refresh()
-    return created
+    try {
+      const created = await $fetch('/api/candidates', {
+        method: 'POST',
+        body: payload,
+      })
+      await refresh()
+      return created
+    } catch (error) {
+      handlePreviewReadOnlyError(error)
+      throw error
+    }
   }
 
   /** Delete a candidate by ID and refresh the list */
   async function deleteCandidate(id: string) {
-    await $fetch(`/api/candidates/${id}`, { method: 'DELETE' })
+    try {
+      await $fetch(`/api/candidates/${id}`, { method: 'DELETE' })
+    } catch (error) {
+      handlePreviewReadOnlyError(error)
+      throw error
+    }
     await refresh()
   }