SuDo is a focused issue tracker and workspace command deck for solo builders, student developers, hackathon teams, and small technical teams. It combines workspace-scoped project management with a compact, dark productivity interface inspired by the clarity and speed of tools such as Linear and Raycast.

The current product includes authenticated workspaces, role-based member management, invitations, projects, assignable issues, comments, labels, search and filters, persisted saved views, activity history, workspace settings, owner-only safe workspace deletion, keyboard-driven commands, and per-user demo workspace seeding. The frontend uses a layered near-black canvas, compact command-deck navigation, restrained acid-lime actions, dense issue tables, contextual drawers, and a responsive product-preview landing page.

Source: github.com/hsusul/SuDo

Live demo: Add the verified Vercel or custom-domain URL here after 20260607033000_saved_views is deployed and post-deploy QA passes.

Demo video: Add the final 60-90 second recording here after capturing it against a sanitized demo workspace.

For a recruiter or interviewer:

1. Open the live application and choose Explore the demo workspace.
2. Sign up or sign in through Clerk.
3. On first-run onboarding, choose Create demo workspace.
4. Open the seeded issue pipeline, then inspect labels, comments, activity, saved views, member settings, and Cmd/Ctrl + K.

The demo workspace is created for the authenticated user. It is not a shared public database and does not reset or mutate another user's work. Repeating the action returns that user's existing demo workspace instead of duplicating it.

Local demo setup:

cp .env.example .env.local
npm install
npm run prisma:migrate
npm run dev

Sign in once so Clerk creates the local User record, set DEMO_SEED_USER_EMAIL in the ignored .env.local, then run:

npm run db:seed
npm run db:verify-demo

The CLI seed targets only that existing synced user. Do not configure DEMO_SEED_USER_EMAIL in production unless an intentional administrative seed is being performed.

• Multi-tenant authorization is enforced server-side for workspace-scoped reads and writes rather than relying on client state.
• Collaboration includes owner/admin/member permissions, hashed expiring invitations, assignees, and activity history.
• Reliability work includes request-scoped auth caching, read-pure listing, concurrency-safe issue numbers, mutation guardrails, loading/error boundaries, structured server logs, CI, and browser tests.
• The deployment path is designed around Vercel, Clerk, Prisma migrations, and pooled/direct Neon Postgres connections.

• Next.js App Router
• TypeScript
• Tailwind CSS v4
• shadcn/ui
• Clerk authentication
• Prisma 7 ORM
• PostgreSQL, with Neon Postgres as the default production recommendation
• Vercel deployment
• Vitest for unit tests
• Playwright and Clerk testing utilities for public and opt-in authenticated E2E tests

flowchart TB
  subgraph Client["Client"]
    Browser["React 19 interface<br/>Tailwind UI + command menu"]
  end

  subgraph Runtime["Vercel runtime"]
    App["Next.js App Router<br/>Server Components + Server Actions"]
    Services["Domain services<br/>Zod validation + authorization"]
  end

  subgraph Identity["Identity"]
    Clerk["Clerk authentication"]
  end

  subgraph Data["Data"]
    Prisma["Prisma ORM"]
    Neon["Neon Postgres"]
  end

  subgraph Quality["Delivery and verification"]
    Actions["GitHub Actions CI"]
    Vitest["Vitest unit/service tests"]
    Playwright["Playwright browser tests"]
    Verifiers["Database relationship verifiers"]
  end

  Browser --> App
  App --> Clerk
  App --> Services
  Services --> Prisma
  Prisma --> Neon
  Actions --> Vitest
  Actions --> Playwright
  Vitest --> Services
  Playwright --> Browser
  Verifiers --> Neon

Technical request path:

1. React and the App Router render the public site and protected workspace UI.
2. Clerk authenticates the request; local user synchronization is cached per request.
3. Server Actions validate input and call domain services.
4. Services recheck workspace membership and role before every scoped read or mutation.
5. Prisma persists tenant-scoped records in Neon Postgres.
6. Vercel hosts the application; GitHub Actions, Vitest, Playwright, and safe database verifiers cover the delivery path.

Security boundaries include server-side tenant authorization, hashed expiring invite tokens, exact-name destructive confirmation, redacted structured logs, security headers, and a report-only CSP compatible with Clerk.

Core data relationships:

• A User can belong to many workspaces through WorkspaceMember.
• A Workspace owns projects, issues, statuses, labels, comments, invitations, saved views, and activity records.
• Projects provide issue keys and scope issue numbering.
• Issues can have an assignee, labels, comments, and append-only activity.
• Saved views persist project and filter state within a workspace.

Authorization roles:

• owner: full workspace use, member management, invitations, and deletion.
• admin: full workspace use plus invitations and supported member management.
• member: product use without member administration or workspace deletion.

Every privileged operation rechecks workspace membership and role on the server. UI visibility is a convenience, not the authorization boundary.

• Responsive product landing page with a CSS-based MacBook product preview.
• Premium Clerk sign-in and sign-up wrappers at /sign-in and /sign-up.
• Protected workspace application at /app.
• Graceful local placeholder mode when Clerk or database env vars are missing.
• Prisma Client generation.
• Prisma schema for users, workspaces, memberships, invitations, projects, issues, labels, comments, activity logs, and demo reset metadata.
• Server-side helper to map the current Clerk user to a local User record when Clerk and DATABASE_URL are configured.
• Workspace onboarding for authenticated users with a configured database.
• Workspace creation that also creates an owner WorkspaceMember row.
• Sidebar workspace switcher for changing workspaces and creating additional workspaces after onboarding.
• Responsive workspace command deck with project, issue, view, and settings navigation.
• Centralized server-side workspace authorization helpers for workspace-scoped reads and writes.
• Workspace roles for owners, admins, and members with centralized permission checks.
• Workspace member list and management controls in Settings.
• Hashed, expiring workspace invitation tokens with pending, accepted, revoked, and expired states.
• Local invite-link acceptance flow that verifies the signed-in user's email.
• Dedicated project page at /app/projects with project listing, creation, rename/edit, and archive inside the selected workspace.
• Server-side project helpers that enforce workspace membership before project reads and writes.
• Dedicated issue page at /app/issues with compact rows, creation, edit, and archive inside the selected project.
• Issue status and priority editing with server-side project/workspace authorization.
• Workspace-member assignees with an explicit unassigned state in issue forms, rows, and drawers.
• URL-backed issue detail drawer using ?issue=<issueId> for refreshable focused editing.
• Issue comments inside the detail drawer with chronological list, author display, timestamp, and composer.
• Compact issue activity history for creation, edits, status, priority, assignee, label, and comment events.
• Workspace labels that can be created, attached to issues, removed from issues, and shown in the issue list and detail drawer.
• Project-scoped custom dropdown filters by status, priority, and label.
• Lightweight issue search by title, description, issue key, and issue number.
• Built-in Views page at /app/views with shortcuts into the existing issue filters.
• Workspace-shared persisted saved views with create, open, rename, delete, and tenant-scoped authorization.
• Command menu opened with Cmd/Ctrl + K, including navigation, create, search, save-view, member, and workspace-switch commands when applicable.
• Settings page at /app/settings with workspace context and a dedicated danger zone.
• Owner-only workspace deletion requiring the exact workspace name, with server-side authorization and deterministic redirect behavior.
• Plain numeric navigation counts plus compact project, issue, and view metadata.
• Reusable panels, page headers, empty states, issue badges, dialogs, buttons, and form controls.

• Add public shared demo reset after the authenticated demo workspace path is deployed and verified.
• Add transactional email delivery for workspace invitations.
• Add notifications only after real delivery and preference semantics are defined.
• Replace per-instance mutation limits with a distributed production limiter.
• Promote the report-only CSP after production violations have been reviewed.
• Add optional error reporting after a provider and privacy policy are chosen.

Install dependencies:

npm install

Create a local environment file:

cp .env.example .env

You can also use .env.local for local secrets. .env.local is ignored by git and is loaded by both Next.js and Prisma CLI commands.

Start the app:

npm run dev

Open http://localhost:3000.

The app can build without Clerk or database secrets. Auth routes and protected behavior show setup placeholders until Clerk environment variables are configured.

GitHub Actions runs npm ci, lint, typecheck, unit tests, the production build, and the repository check script for pushes to main and pull requests. These checks intentionally run without Clerk or database secrets. CI supplies a non-secret localhost database URL only so Prisma can generate its client; it does not connect to a database.

Database verifier scripts are not part of CI because they inspect a configured Postgres database. Run them only from a trusted local or deployment environment where the intended database variables are loaded. The in-process mutation rate limits are basic per-instance abuse guardrails; production-wide enforcement across multiple Vercel instances should use Vercel Firewall or a shared rate limit store.

Current verification baseline:

• 113 Vitest unit/service tests across 27 files.
• 4 public Playwright smoke tests, including security-header assertions.
• 4 authenticated Playwright setup/workflow tests that are intentionally skipped unless dedicated Clerk test accounts are configured.
• Secret-free GitHub Actions for install, lint, typecheck, unit tests, build, and the repository check script.

SuDo uses three browser QA paths:

• Interactive visual review with the Codex in-app Browser or Playwright MCP when available.
• Repeatable public smoke checks with the Playwright test runner.
• Opt-in authenticated Playwright workflows using Clerk test accounts and reusable storageState.

Run public browser smoke tests:

npm run test:e2e

Run headed:

npm run test:e2e:headed

Open Playwright UI:

npm run test:e2e:ui

Capture safe public screenshots under test-results/:

npm run qa:screenshots

If browsers are missing on a new machine:

npx playwright install chromium

The default E2E suite covers /, /sign-in, /sign-up, signed-out /app protection, and responsive landing-page smoke checks. It does not hardcode Clerk credentials or bypass auth.

Authenticated tests use @clerk/testing with a Clerk development instance. Create dedicated test users in that instance, then add their email addresses to your ignored .env.local:

E2E_CLERK_USER_EMAIL="owner-test@example.com"
E2E_CLERK_MEMBER_EMAIL="member-test@example.com"

Run the authenticated suite:

npm run test:e2e:auth

E2E_CLERK_MEMBER_EMAIL is optional. Without it, the second-account invite, acceptance, role-change, and tenant-isolation test is skipped. The owner suite still covers app smoke, workspace/project/issue workflows, assignees, labels, comments, activity, filters, saved views, command shortcuts, archiving, and exact-name deletion.

Clerk auth state is written to playwright/.clerk/owner.json, which is ignored by git. Never commit storage-state files, test credentials, or screenshots with private data. GitHub Actions remains secret-free and runs the non-authenticated verification path only.

Create a Clerk application, then add these values to .env:

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=""
CLERK_SECRET_KEY=""
NEXT_PUBLIC_CLERK_SIGN_IN_URL="/sign-in"
NEXT_PUBLIC_CLERK_SIGN_UP_URL="/sign-up"
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL="/app/issues"
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL="/app/issues"
NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL="/app/issues"
NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL="/app/issues"

# Optional local-only authenticated Playwright users
E2E_CLERK_USER_EMAIL=""
E2E_CLERK_MEMBER_EMAIL=""

When both NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY are present:

• /app is protected by src/proxy.ts.
• Clerk sign-in/sign-up components render.
• Server helpers can read the current Clerk user.
• /app can sync the Clerk user into the local Prisma User table when DATABASE_URL is also configured.

Do not commit .env files or real secret values.

Prisma is configured for PostgreSQL. Use local Postgres, Neon, Supabase Postgres, or another Postgres-compatible database.

Add a valid DATABASE_URL to .env.local or .env:

DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public"

If your provider gives you both pooled and direct connection strings, keep DATABASE_URL as the runtime URL and add the direct, non-pooled URL for migrations:

DIRECT_DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public"

Generate Prisma Client:

npm run prisma:generate

Run the first migration only after DATABASE_URL points at a real development database:

npm run prisma:migrate

The collaboration vertical slice is introduced by migration 20260607023000_collaboration_vertical_slice. Persisted saved views are introduced by migration 20260607033000_saved_views. Deploy committed migrations before using these features in an existing environment:

npm run prisma:migrate:status
npm run prisma:migrate:deploy

Prisma 7 reads environment variables through prisma.config.ts. This repo loads .env first and .env.local second, so local secrets in .env.local can override shared defaults without being committed. Shell-provided environment variables still take precedence for one-off commands. If DIRECT_DATABASE_URL is present, Prisma CLI migration commands use it; otherwise they fall back to DATABASE_URL.

Open Prisma Studio:

npm run prisma:studio

Run the seed placeholder:

npm run db:seed

The default seed command is safe and does not fake auth users. To create a demo workspace for an existing synced Clerk user, sign in once so a local User row exists, set DEMO_SEED_USER_EMAIL to that user's email in .env.local, then run:

npm run db:seed

This creates or returns one demo workspace for that existing user. It does not reset or mutate other users' workspaces.

curl -H "Accept: text/html" -I http://localhost:3000/app

npm run db:verify-workspace

npm run db:verify-projects

npm run db:verify-issues

npm run db:verify-comments

npm run db:verify-labels

npm run db:verify-filters

npm run db:verify-views

npm run db:verify-settings

npm run db:verify-counts

npm run db:verify-demo

• If /app throws that clerkMiddleware() was not run, confirm the Clerk proxy is at src/proxy.ts for this src/app project layout.
• If /app shows setup messaging, confirm both Clerk keys and DATABASE_URL are present in .env.local or .env.
• If npm run prisma:migrate cannot see DATABASE_URL, confirm prisma.config.ts still loads .env and .env.local.
• If npm run prisma:migrate reaches Neon but times out on an advisory lock, confirm migrations are using DIRECT_DATABASE_URL with a direct, non-pooled connection string.
• If Prisma connects but no onboarding rows appear, make sure you completed sign-in and submitted the workspace form in the browser; the database is not seeded with real user workspaces yet.

npm run dev
npm run lint
npm run typecheck
npm run test
npm run check
npm run test:e2e
npm run test:e2e:auth
npm run test:e2e:headed
npm run test:e2e:ui
npm run qa:screenshots
npm run build
npm run prisma:generate
npm run prisma:migrate
npm run prisma:migrate:status
npm run prisma:migrate:deploy
npm run prisma:studio
npm run db:seed
npm run db:verify-workspace
npm run db:verify-projects
npm run db:verify-issues
npm run db:verify-comments
npm run db:verify-labels
npm run db:verify-filters
npm run db:verify-demo
npm run db:verify-views
npm run db:verify-settings
npm run db:verify-counts
./scripts/check.sh

The production target is Vercel for the Next.js app, Neon Postgres for hosted Postgres, and Clerk for production authentication. Do not deploy with local development secrets, and do not run destructive Prisma commands against production.

• GitHub repository: https://github.com/hsusul/SuDo
• Vercel account.
• Neon account.
• Clerk account.
• A clean local check before pushing:

npm run check

1. Create a new Neon project for SuDo production.
2. Copy the pooled Neon connection string into DATABASE_URL.
3. Copy the direct, non-pooled Neon connection string into DIRECT_DATABASE_URL.
4. Keep the pooled URL for runtime traffic and the direct URL for Prisma migrations.

In Clerk:

1. Create or switch to a production Clerk application.
2. Copy the production publishable key into NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3. Copy the production secret key into CLERK_SECRET_KEY.
4. Configure sign-in URL: /sign-in.
5. Configure sign-up URL: /sign-up.
6. Configure after sign-in URL: /app/issues.
7. Configure after sign-up URL: /app/issues.
8. Configure fallback redirect URLs to /app/issues if Clerk asks for them.
9. After the first Vercel deploy, add the Vercel URL and any custom domain to Clerk allowed origins/domains.

The most common production auth bug is a Clerk redirect or allowed-domain mismatch.

In Vercel:

1. Import https://github.com/hsusul/SuDo.
2. Framework preset: Next.js.
3. Install command: npm install.
4. Build command: npm run build.
5. Output directory: use the Next.js default.

The repo does not need a postinstall Prisma hook because npm run build already runs prisma generate through prebuild.

Add these in Vercel Project Settings for Production. Add Preview values only if you plan to test preview deployments with a preview Clerk/database setup.

NEXT_PUBLIC_APP_URL="https://your-vercel-domain.vercel.app"

DATABASE_URL="postgresql://USER:PASSWORD@HOST/DATABASE?sslmode=require"
DIRECT_DATABASE_URL="postgresql://USER:PASSWORD@HOST/DATABASE?sslmode=require"

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_live_..."
CLERK_SECRET_KEY="sk_live_..."

NEXT_PUBLIC_CLERK_SIGN_IN_URL="/sign-in"
NEXT_PUBLIC_CLERK_SIGN_UP_URL="/sign-up"
NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL="/app/issues"
NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL="/app/issues"
NEXT_PUBLIC_CLERK_SIGN_IN_FALLBACK_REDIRECT_URL="/app/issues"
NEXT_PUBLIC_CLERK_SIGN_UP_FALLBACK_REDIRECT_URL="/app/issues"

Notes:

• Never commit real values. .env.local and .env.production are ignored.
• Vercel environment variable changes require a new deployment.
• DATABASE_URL is used by the app at runtime.
• DIRECT_DATABASE_URL is preferred by prisma.config.ts for Prisma CLI migration commands.

1. Trigger the first Vercel deployment.
2. Copy the generated Vercel URL.
3. Add that URL to Clerk allowed origins/domains.
4. Redeploy in Vercel after Clerk domain and env-var changes.

Run production migrations only with production env vars intentionally loaded:

npm run prisma:migrate:deploy

prisma migrate deploy applies committed migrations without creating a new migration, without a shadow database, and without resetting data.

Do not run these against production:

npm run prisma:migrate
prisma migrate dev
prisma migrate reset
prisma db push

If Neon advisory locks or pooled-connection issues appear, confirm DIRECT_DATABASE_URL is a direct, non-pooled connection string.

Open the deployed URL in a clean browser session:

1. / loads.
2. /sign-in loads production Clerk UI.
3. /sign-up loads production Clerk UI.
4. /app redirects signed-out visitors to Clerk.
5. Sign up or sign in.
6. Create a blank workspace or choose Create demo workspace.
7. Create a project.
8. Create an issue.
9. Open the issue drawer.
10. Add a comment.
11. Create/attach/remove a label.
12. Use status, priority, label, and search filters.
13. Switch workspaces if more than one exists.
14. Open Views and Settings.
15. Invite a second Clerk account, accept the invitation with the matching email, and assign an issue to that member.
16. Confirm issue activity records the collaboration changes.
17. Confirm no secret values appear in browser output, Vercel logs, or docs.

Optional production verifier commands can be run only from a safe environment where production database env vars are intentionally loaded:

npm run db:verify-workspace
npm run db:verify-projects
npm run db:verify-issues
npm run db:verify-comments
npm run db:verify-labels
npm run db:verify-filters
npm run db:verify-demo
npm run db:verify-views
npm run db:verify-settings
npm run db:verify-counts

• Clerk redirect mismatch: add the Vercel URL/custom domain to Clerk allowed origins/domains and redeploy.
• Missing Vercel env vars: add every required env var for the Production environment and redeploy.
• Env vars changed but app still behaves the same: trigger a new deployment.
• Prisma cannot find DATABASE_URL: confirm it exists in the environment where the Prisma command is running.
• Neon migration timeout: use a direct, non-pooled DIRECT_DATABASE_URL.
• Vercel build failure around Prisma Client: run npm run prisma:generate and npm run build locally, then check that migrations and schema are committed.
• Runtime database errors after a successful build: verify the production database URL, SSL settings, and that npm run prisma:migrate:deploy ran.
• Demo creation fails after sign-in: verify migrations ran and the signed-in user reached /app so SuDo could sync a local User row.

Do not commit secrets, browser auth state, database URLs, invitation tokens, or screenshots containing private workspace data.

Before release:

• Pull the intended commit and confirm the working tree contains only the release changes.
• Run npm ci.
• Run npm run lint, npm run typecheck, npm run test, npm run build, and npm run check.
• Run npm run test:e2e.
• Run npm run test:e2e:auth only when dedicated Clerk test accounts are configured locally.
• Run npm run prisma:migrate:status against the intended database.
• Review every pending migration. The saved-view release requires 20260607033000_saved_views.
• Confirm Vercel Production has the required Clerk, app URL, pooled DATABASE_URL, and direct DIRECT_DATABASE_URL values.
• Confirm Clerk allows the production domain.

Release:

• Intentionally load the production Neon environment.
• Run npm run prisma:migrate:deploy.
• Run npm run prisma:migrate:status again and confirm no migration is pending.
• Redeploy the exact verified commit to Vercel.
• Complete the post-deploy QA checklist below.
• Review Vercel runtime logs for failed requests, action failures, auth redirects, slow pages, and database connection errors.

Rollback:

1. Stop the rollout or promote the previous known-good Vercel deployment.
2. Do not use prisma migrate reset, prisma db push, or manually delete a production migration.
3. For an additive migration such as saved views, leave the added table in place while rolling back application code.
4. For a future destructive migration, prepare and test a forward-fix migration and a Neon restore plan before release.
5. Record the failed release commit, symptoms, relevant safe log event names, and recovery action.

next.config.ts applies the following response headers to all routes:

• X-Frame-Options: DENY
• X-Content-Type-Options: nosniff
• Referrer-Policy: strict-origin-when-cross-origin
• a restrictive Permissions-Policy
• one-year HSTS without preload
• Content-Security-Policy-Report-Only

The CSP blocks framing and object embeds while allowing the Clerk and Cloudflare challenge origins needed by authentication. It remains report-only because Next.js development scripts, inline styles, and Clerk can require careful nonce-based configuration. Review browser and deployment violations before promoting the policy to enforcement. The current policy does not use a reporting endpoint, so local browser console inspection and deployment smoke tests are the initial validation path. See the Next.js CSP guide and Clerk CSP guidance.

Server authorization denials, failed mutations, invitation failures, saved-view failures, and workspace deletion attempts emit one-line JSON events suitable for Vercel Runtime Logs. Entries can include event name, operation, environment, opaque record IDs, role, status, and safe error class/code.

Never add these values to log context:

• emails, names, issue titles, descriptions, comments, or request bodies
• cookies, authorization headers, Clerk tokens, invitation tokens or hashes
• database URLs, DSNs, secrets, passwords, or environment values
• raw error messages or stacks from database and provider failures

Unexpected server-action errors return a generic user-facing fallback instead of exposing an arbitrary exception message.

Use the Vercel project dashboard's Logs view during and after deployment. Filter by production environment, deployment, route, status code, and time range. Check:

• mutation.failed and authorization.* structured events
• repeated Clerk redirects or missing-user failures
• Prisma connection, pool exhaustion, or migration errors
• slow issue, view, and settings routes
• elevated 4xx/5xx responses after release

Vercel Runtime Logs are available without adding a runtime dependency. Optional paid observability features should be labeled before adoption. See Vercel Runtime Logs.

Sentry is not installed in this pass. The structured logs and existing route error boundaries keep the application dependency-free, but they do not provide cross-request traces, alerting, or source-mapped exception aggregation.

Recommended future setup:

1. Install @sentry/nextjs and use Sentry's official Next.js setup.
2. Keep SENTRY_DSN and NEXT_PUBLIC_SENTRY_DSN optional.
3. Store SENTRY_AUTH_TOKEN only in the deployment environment for source-map upload; never expose it to the browser or commit it.
4. Redact user content and auth data before sending events.
5. Verify a test event in Preview before enabling Production alerts.

See Sentry for Next.js.

Current mutation guardrails are process-local. They limit accidental bursts within one warm Vercel instance, but they are not a production-wide abuse boundary and reset when instances recycle.

Preferred production options:

1. Use Vercel Firewall rate-limiting rules for coarse route/IP protection where the plan supports it.
2. Use a shared Redis-backed limiter, such as Upstash, for authenticated user/workspace mutation keys that must be consistent across instances.
3. Keep authorization and validation in server actions even when an edge rule rejects obvious abuse.

Do not use the primary Neon application tables as a high-frequency rate-limit counter without load testing and a cleanup design. See Vercel Firewall rate limiting and Upstash Ratelimit.

• Keep production on a protected Neon branch and use separate development or preview branches for migration rehearsal.
• Point Vercel Preview deployments at preview data and a development Clerk instance. Never let untrusted preview code use production database secrets.
• Use the pooled URL for application traffic and the direct URL for Prisma migration commands.
• Run prisma migrate status, inspect SQL, test on a branch, and take note of the restore window before destructive migrations.
• Neon restore creates a new branch at a selected point in time. Test recovery by restoring to a separate branch, validating schema and representative records, and connecting a non-production app or verifier to that branch.
• Do not overwrite or delete the production branch during a restore exercise.
• Before destructive changes, prefer expand-and-contract migrations, retain backward compatibility for one release, and document the forward recovery path.

References: Neon branching and Neon restore.

The June 7, 2026 audit reports moderate advisories in the direct Next.js and Prisma toolchain plus transitive postcss, @prisma/dev, and @hono/node-server packages. No high or critical advisory was reported.

npm audit fix --force is intentionally not used because npm currently proposes breaking or inappropriate major downgrades for this dependency graph. Follow-up:

1. Apply compatible patch updates for Next.js, eslint-config-next, Clerk, and development tooling in a dedicated upgrade change.
2. Re-run lint, typecheck, unit tests, build, Playwright, and npm audit.
3. Track Prisma and Next.js upstream releases that resolve the remaining transitive advisories.
4. Reassess immediately if severity increases or an exploit applies to SuDo's deployed paths.

• Landing page, sign-in, and sign-up render on desktop and mobile.
• Signed-out /app redirects to sign-in without a loop.
• Sign in and sign up with production Clerk.
• Create and switch workspaces.
• Create, rename, and archive a project.
• Create, open, edit, assign, unassign, label, and archive an issue.
• Add a comment and confirm activity history.
• Apply search, status, priority, and label filters.
• Create, open, rename, and delete a saved view.
• Open Cmd/Ctrl + K and run navigation and create commands.
• Create, revoke, and accept an invitation with the matching account.
• Verify owner/admin/member controls and server-side denials.
• Confirm wrong workspace-delete text stays blocked and exact text deletes.
• Check narrow mobile navigation, dialogs, forms, and issue drawer.
• Confirm security headers on the production response.
• Review Vercel runtime logs and database connection health.

No private or stale screenshots are committed. Capture current production or sanitized local images using these exact paths:

Capture guidance:

• Use a seeded demo workspace and replace any real email addresses.
• Never capture invite tokens, Clerk internals, browser auth state, or private workspace data.
• Prefer WebP at 1600x1000 or similar, under roughly 500 KB per desktop image.
• Keep browser chrome out of the frame unless it helps establish the live URL.
• Verify text remains readable at GitHub's rendered README width.

After adding reviewed images, place a compact screenshot grid near the top of this README rather than embedding every workflow at full size.

0-10 seconds: "SuDo is a deployed multi-tenant issue tracker for small technical teams. I built it with Next.js, TypeScript, Clerk, Prisma, Neon Postgres, and Vercel."

10-23 seconds: Sign in and create the seeded demo workspace. Open a project and create an issue. Point out the compact issue ID, status, priority, and assignee.

23-36 seconds: Add a label, apply search or priority filters, and save the current filter state as a named view.

36-49 seconds: Open the issue drawer, add a comment, change the assignee, and show the activity timeline recording those changes.

49-61 seconds: Open Settings. Show members, pending invitations, and the owner/admin/member permission model. Briefly show that workspace deletion requires both owner authorization and the exact workspace name.

61-69 seconds: Press Cmd/Ctrl + K and navigate to another product area.

69-75 seconds: "The app is deployed on Vercel with Clerk auth and Neon Postgres. It has 113 unit tests, public and authenticated Playwright coverage, CI, security headers, and redacted structured logging."

Keep the recording conversational. Show one complete workflow rather than opening every page.

• Built and deployed a multi-tenant issue tracker using Next.js 16, TypeScript, Clerk, Prisma, Neon Postgres, and Vercel, with owner/admin/member RBAC, hashed invitations, assignees, activity history, saved views, and Cmd/Ctrl + K workflows.
• Implemented tenant-scoped Server Actions and authorization across workspaces, projects, issues, comments, labels, memberships, and saved views; added concurrency-safe issue numbering, read-pure queries, and owner-protected destructive operations.
• Established production verification with 113 Vitest tests, 4 public Playwright checks, 4 optional authenticated Playwright workflows, GitHub Actions CI, database relationship verifiers, security headers, and redacted JSON runtime logs.

The difficult part was preserving tenant correctness across many related workflows rather than implementing isolated CRUD screens. Each project, issue, comment, label, assignee, invitation, and saved view must be derived from an authorized workspace on the server. Issue creation also needed concurrency-safe numbering without turning ordinary issue listing into a write.

Clerk establishes identity, while SuDo stores a local user record for relational data. Request-scoped caching avoids repeated Clerk lookups and user upserts. Workspace access helpers load the membership and active workspace together; role helpers then enforce owner/admin/member permissions. Client-provided workspace IDs are never treated as proof of access.

WorkspaceMember models the many-to-many user/workspace relationship and role. Workspace-owned records carry explicit workspace scope, while projects own human-readable issue sequences. Invitations store token hashes and expiry state. Activity records are append-only product history, and saved views store validated filter configuration as JSON.

Vercel hosts the Next.js application, Clerk provides production auth, and Neon provides pooled runtime plus direct migration connections. Releases verify pending migrations, run prisma migrate deploy, redeploy the tested commit, complete browser smoke checks, and inspect structured runtime logs.

Vitest covers validation, authorization, tenant isolation, issue numbering, read purity, collaboration, deletion safety, and saved views. Public Playwright tests cover responsive routes, auth redirects, and security headers. Authenticated workflows use Clerk test accounts and reusable storage state when credentials are explicitly configured. Database verifiers inspect persisted relationships outside secret-free CI.

The product deliberately favors a strong list/detail workflow over kanban, real-time presence, or notification breadth. Invitations use shareable links because transactional email is not configured. The next production investments would be distributed rate limiting, enforced nonce-based CSP, alerting, email delivery, and fully configured authenticated E2E in a dedicated test environment.

• Authenticated Playwright workflows require dedicated Clerk development test accounts and are skipped in secret-free CI.
• CSP is report-only until Clerk/Next.js violations are reviewed and a nonce-based enforcement strategy is validated.
• Mutation limits are in-process per Vercel instance, not distributed.
• Invitations use secure expiring links but do not yet send transactional email.
• There are no real-time notifications, mentions, or presence indicators.
• Sentry or equivalent alerting and cross-request tracing are not configured.
• Five moderate Next.js/Prisma toolchain and transitive audit advisories are tracked; forced breaking downgrades are intentionally not applied.
• The saved-views migration must be applied with npm run prisma:migrate:deploy before deploying that feature version.