From Idea to Production in One Day — Complete Workflow Guide

# LinkVault — MVP Plan

## Tech Stack Decision
- Next.js 15 (App Router) — fast to develop, easy to deploy on Vercel
- PostgreSQL (Supabase) — free tier, managed, full-text search built in
- Prisma — type-safe database access
- NextAuth.js — Google + GitHub auth (developers already have these accounts)
- Tailwind CSS + shadcn/ui — consistent, professional UI
- Vercel — deployment with preview URLs

## Database Schema
- User: id, name, email, image, apiKey, createdAt
- Link: id, url, title, description, userId, collectionId, createdAt
- Tag: id, name, userId
- LinkTag: linkId, tagId
- Collection: id, name, userId, createdAt

## MVP Pages
- / — landing page
- /dashboard — saved links with search and filter
- /collections — manage collections
- /settings — API key, import bookmarks, account
- /api/links — REST API for CLI and extension

## Priority Order
1. Auth + database schema (foundation)
2. Save and list links (core feature)
3. Search and tags (the differentiator)
4. Collections (organization)
5. API + API key (developer feature)
6. Chrome extension (convenience)
7. Import from browser (onboarding)
8. Polish and deploy

## Non-MVP (Future)
- AI tag suggestions
- Link health checking (detect broken links)
- Sharing collections publicly
- Team collections
- CLI tool (npm package)

Create a bookmark manager called "LinkVault" with Next.js 15 App Router.

Phase 1 — Foundation:

1. Landing page at / with:
   - Hero: "Your developer bookmarks, organized and searchable"
   - Features: full-text search, tags, collections, API access, browser extension
   - CTA: "Get Started — Free" button linking to auth
   - Clean design with Tailwind + shadcn/ui

2. Auth with NextAuth.js:
   - GitHub provider (primary — developers already have GitHub)
   - Google provider (secondary)
   - Session in JWT

3. Database (Prisma + Supabase PostgreSQL):
   - User: id, name, email, image, apiKey (uuid, generated on first login), createdAt
   - Link: id, url, title, description, favicon, userId, collectionId (nullable),
     createdAt, updatedAt
   - Tag: id, name, color, userId
   - LinkTag: linkId, tagId (composite primary key)
   - Collection: id, name, icon, userId, createdAt

4. Middleware: protect /dashboard/* routes, redirect unauthenticated to /

5. Basic dashboard shell at /dashboard:
   - Sidebar: collections list, tags list
   - Main area: placeholder for link list
   - Header: search bar, "Add Link" button, user avatar

Add the core feature — saving and listing links:

1. "Add Link" dialog (opened from header button):
   - URL input (required)
   - When URL is entered, auto-fetch title, description, and favicon from the page
   - Title input (pre-filled from fetch, editable)
   - Description textarea (pre-filled, editable)
   - Tag selector: multi-select from existing tags or create new
   - Collection selector: optional dropdown
   - "Save" button

2. Auto-fetch endpoint: POST /api/links/fetch-metadata
   - Accept { url }
   - Fetch the page HTML server-side
   - Extract: title (og:title or <title>), description (og:description or meta description),
     favicon (link[rel="icon"])
   - Return { title, description, favicon }
   - Timeout: 5 seconds, return empty strings on failure

3. Link list on dashboard:
   - Card layout: favicon + title + description + tags + domain + saved date
   - Grid of cards (responsive: 1 col mobile, 2 col tablet, 3 col desktop)
   - Click card to open URL in new tab
   - Edit button (pencil icon) on hover
   - Delete button (trash icon) on hover with confirmation
   - Infinite scroll pagination (20 links per page)

4. API route: POST /api/links, GET /api/links, PATCH /api/links/:id, DELETE /api/links/:id

export async function POST(req: NextRequest) {
  const { url } = await req.json();

  try {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), 5000);

    const response = await fetch(url, {
      signal: controller.signal,
      headers: { "User-Agent": "LinkVault/1.0 (metadata fetcher)" },
    });
    clearTimeout(timeout);

    const html = await response.text();

    // Parse metadata
    const titleMatch = html.match(/<meta\s+property="og:title"\s+content="([^"]*)"/) ||
                       html.match(/<title>([^<]*)<\/title>/);
    const descMatch = html.match(/<meta\s+property="og:description"\s+content="([^"]*)"/) ||
                      html.match(/<meta\s+name="description"\s+content="([^"]*)"/) ;
    const faviconMatch = html.match(/<link\s+[^>]*rel="(?:shortcut )?icon"[^>]*href="([^"]*)"/);

    const title = titleMatch?.[1] || "";
    const description = descMatch?.[1] || "";
    let favicon = faviconMatch?.[1] || "";

    // Resolve relative favicon URL
    if (favicon && !favicon.startsWith("http")) {
      const base = new URL(url);
      favicon = new URL(favicon, base.origin).toString();
    }

    if (!favicon) {
      favicon = `${new URL(url).origin}/favicon.ico`;
    }

    return NextResponse.json({ title, description, favicon });
  } catch {
    return NextResponse.json({ title: "", description: "", favicon: "" });
  }
}

function LinkCard({ link, onEdit, onDelete }: LinkCardProps) {
  return (
    <div className="group relative bg-white rounded-xl border p-4 hover:shadow-md transition-shadow">
      <a href={link.url} target="_blank" rel="noopener noreferrer" className="block">
        <div className="flex items-start gap-3">
          <img
            src={link.favicon || "/default-favicon.png"}
            alt=""
            className="w-6 h-6 rounded mt-0.5"
            onError={(e) => { (e.target as HTMLImageElement).src = "/default-favicon.png" }}
          />
          <div className="flex-1 min-w-0">
            <h3 className="font-medium text-gray-900 truncate">{link.title}</h3>
            <p className="text-sm text-gray-500 line-clamp-2 mt-1">{link.description}</p>
            <div className="flex items-center gap-2 mt-2">
              <span className="text-xs text-gray-400">{new URL(link.url).hostname}</span>
              <span className="text-xs text-gray-300">|</span>
              <span className="text-xs text-gray-400">
                {formatDistanceToNow(new Date(link.createdAt), { addSuffix: true })}
              </span>
            </div>
            {link.tags.length > 0 && (
              <div className="flex flex-wrap gap-1 mt-2">
                {link.tags.map((tag) => (
                  <span
                    key={tag.id}
                    className="px-2 py-0.5 text-xs rounded-full"
                    style={{ backgroundColor: tag.color + "20", color: tag.color }}
                  >
                    {tag.name}
                  </span>
                ))}
              </div>
            )}
          </div>
        </div>
      </a>

      {/* Actions on hover */}
      <div className="absolute top-2 right-2 opacity-0 group-hover:opacity-100 transition-opacity flex gap-1">
        <button
          onClick={(e) => { e.preventDefault(); onEdit(link); }}
          className="p-1.5 rounded-md bg-gray-100 hover:bg-gray-200 text-gray-500"
        >
          <PencilIcon className="w-4 h-4" />
        </button>
        <button
          onClick={(e) => { e.preventDefault(); onDelete(link.id); }}
          className="p-1.5 rounded-md bg-gray-100 hover:bg-red-100 text-gray-500 hover:text-red-500"
        >
          <TrashIcon className="w-4 h-4" />
        </button>
      </div>
    </div>
  );
}

Add full-text search and tag management:

1. Search:
   - Search bar in header — search across title, description, URL, and tags
   - Use PostgreSQL full-text search (tsvector + tsquery) via Prisma raw query
   - Show results as you type (debounce 300ms)
   - Highlight matching terms in results

2. Tag management:
   - Tags in sidebar: show tag list with link count
   - Click tag to filter links
   - Create new tags inline (type name + press Enter)
   - Tag colors: auto-assign from a preset palette
   - Edit tag: rename, change color
   - Delete tag: remove from all links

3. Combined filtering:
   - Search + tag filter work together (AND logic)
   - URL query params: ?q=search&tag=react&collection=default
   - Browser back/forward works with filters

async function searchLinks(userId: string, query: string, tagId?: string, collectionId?: string) {
  let where: any = { userId };

  if (tagId) {
    where.tags = { some: { tagId } };
  }

  if (collectionId) {
    where.collectionId = collectionId;
  }

  if (query) {
    // Use PostgreSQL full-text search
    const links = await prisma.$queryRaw`
      SELECT l.*,
        ts_rank(
          to_tsvector('english', l.title || ' ' || COALESCE(l.description, '') || ' ' || l.url),
          plainto_tsquery('english', ${query})
        ) as rank
      FROM "Link" l
      WHERE l."userId" = ${userId}
        AND to_tsvector('english', l.title || ' ' || COALESCE(l.description, '') || ' ' || l.url)
            @@ plainto_tsquery('english', ${query})
      ORDER BY rank DESC
      LIMIT 50
    `;
    return links;
  }

  return prisma.link.findMany({
    where,
    include: { tags: { include: { tag: true } } },
    orderBy: { createdAt: "desc" },
    take: 50,
  });
}

function TagSidebar({ tags, activeTag, onSelectTag }: TagSidebarProps) {
  const [newTagName, setNewTagName] = useState("");

  const createTag = async () => {
    if (!newTagName.trim()) return;
    const colors = ["#ef4444", "#f59e0b", "#10b981", "#3b82f6", "#8b5cf6", "#ec4899"];
    const color = colors[Math.floor(Math.random() * colors.length)];

    await fetch("/api/tags", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ name: newTagName.trim(), color }),
    });

    setNewTagName("");
    // Refetch tags...
  };

  return (
    <div className="space-y-1">
      <h3 className="text-xs font-semibold text-gray-500 uppercase px-2 mb-2">Tags</h3>

      {tags.map((tag) => (
        <button
          key={tag.id}
          onClick={() => onSelectTag(tag.id)}
          className={`w-full flex items-center gap-2 px-2 py-1.5 rounded-md text-sm ${
            activeTag === tag.id ? "bg-gray-100" : "hover:bg-gray-50"
          }`}
        >
          <span
            className="w-2.5 h-2.5 rounded-full"
            style={{ backgroundColor: tag.color }}
          />
          <span className="flex-1 text-left truncate">{tag.name}</span>
          <span className="text-xs text-gray-400">{tag._count.links}</span>
        </button>
      ))}

      {/* Inline new tag */}
      <div className="px-2 pt-2">
        <input
          value={newTagName}
          onChange={(e) => setNewTagName(e.target.value)}
          onKeyDown={(e) => e.key === "Enter" && createTag()}
          placeholder="New tag..."
          className="w-full text-sm px-2 py-1 border rounded-md"
        />
      </div>
    </div>
  );
}

Add collections (folders for organizing links):

1. Collections page at /dashboard/collections:
   - List all collections with link count
   - Create collection: name + optional icon (emoji)
   - Edit and delete collections
   - Default collection: "Unsorted" (cannot be deleted)

2. Collection filter in sidebar:
   - Show collections above tags
   - Click to filter links by collection
   - "All Links" option at the top

3. Move links between collections:
   - In link edit dialog, add collection dropdown
   - Drag link to collection in sidebar (stretch goal — skip if complex)

4. Bulk actions:
   - Select multiple links with checkboxes
   - Bulk move to collection
   - Bulk add tag
   - Bulk delete

function BulkActionBar({ selectedCount, onMove, onTag, onDelete }: BulkActionBarProps) {
  if (selectedCount === 0) return null;

  return (
    <div className="sticky top-0 z-10 bg-blue-50 border-b border-blue-200 p-3 flex items-center gap-4">
      <span className="text-sm font-medium text-blue-800">
        {selectedCount} selected
      </span>

      <button onClick={onMove} className="text-sm text-blue-600 hover:text-blue-800">
        Move to collection
      </button>
      <button onClick={onTag} className="text-sm text-blue-600 hover:text-blue-800">
        Add tag
      </button>
      <button onClick={onDelete} className="text-sm text-red-600 hover:text-red-800">
        Delete
      </button>
    </div>
  );
}

Add developer API access:

1. API key management in /dashboard/settings:
   - Show current API key (masked with "reveal" button)
   - "Regenerate" button with confirmation
   - Copy to clipboard button
   - API key is a UUID generated on first login

2. API authentication middleware:
   - Accept API key via X-API-Key header
   - Look up user by API key
   - Apply to all /api/v1/* routes

3. Public API endpoints (authenticated via API key):
   - GET /api/v1/links — list links (with search, tag, collection filters)
   - POST /api/v1/links — save a new link
   - PATCH /api/v1/links/:id — update a link
   - DELETE /api/v1/links/:id — delete a link
   - GET /api/v1/tags — list tags
   - GET /api/v1/collections — list collections

4. API docs page at /docs:
   - Simple documentation showing all endpoints with curl examples
   - Rate limit: 100 requests/minute

5. Rate limiting:
   - In-memory rate limiter (simple token bucket)
   - Return 429 with Retry-After header when exceeded

export async function withApiAuth(req: NextRequest): Promise<{ user: User } | NextResponse> {
  const apiKey = req.headers.get("x-api-key");

  if (!apiKey) {
    return NextResponse.json(
      { error: "API key required. Pass via X-API-Key header." },
      { status: 401 }
    );
  }

  const user = await prisma.user.findUnique({ where: { apiKey } });

  if (!user) {
    return NextResponse.json({ error: "Invalid API key" }, { status: 401 });
  }

  return { user };
}

function ApiDocsPage() {
  return (
    <div className="max-w-3xl mx-auto py-12 px-4">
      <h1 className="text-3xl font-bold mb-2">LinkVault API</h1>
      <p className="text-gray-500 mb-8">Access your bookmarks programmatically.</p>

      <div className="space-y-8">
        <ApiEndpoint
          method="GET"
          path="/api/v1/links"
          description="List your saved links"
          params={[
            { name: "q", type: "string", description: "Search query" },
            { name: "tag", type: "string", description: "Filter by tag name" },
            { name: "collection", type: "string", description: "Filter by collection name" },
            { name: "limit", type: "number", description: "Results per page (default: 20, max: 100)" },
            { name: "offset", type: "number", description: "Pagination offset" },
          ]}
          example={`curl -H "X-API-Key: your-api-key" \\
  https://linkvault.app/api/v1/links?q=react&limit=10`}
        />

        <ApiEndpoint
          method="POST"
          path="/api/v1/links"
          description="Save a new link"
          body={{
            url: "https://example.com/article",
            title: "Optional title (auto-fetched if omitted)",
            description: "Optional description",
            tags: ["react", "tutorial"],
            collection: "Frontend",
          }}
          example={`curl -X POST -H "X-API-Key: your-api-key" \\
  -H "Content-Type: application/json" \\
  -d '{"url": "https://react.dev", "tags": ["react"]}' \\
  https://linkvault.app/api/v1/links`}
        />

        {/* More endpoints... */}
      </div>
    </div>
  );
}

Create a Chrome extension for quick link saving:

1. Manifest V3 popup extension
2. Popup shows:
   - Current page title and URL (pre-filled)
   - Tag selector (fetches tags from API)
   - Collection selector (fetches collections from API)
   - "Save" button
   - Success/error message

3. Settings:
   - API key input (saved in chrome.storage.sync)
   - API URL input (default: https://linkvault.app)

4. Keyboard shortcut: Ctrl+Shift+S to open popup and save current page

5. When the page has an existing bookmark, show "Already saved" instead of the save form

Keep it minimal — popup only, no background scripts beyond the keyboard shortcut.

{
  "manifest_version": 3,
  "name": "LinkVault",
  "version": "1.0.0",
  "description": "Save bookmarks to LinkVault with one click",
  "permissions": ["activeTab", "storage"],
  "action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "icons/icon16.png",
      "48": "icons/icon48.png",
      "128": "icons/icon128.png"
    }
  },
  "commands": {
    "_execute_action": {
      "suggested_key": { "default": "Ctrl+Shift+S" },
      "description": "Save current page to LinkVault"
    }
  }
}

<div id="app">
  <div id="loading" class="text-center py-4">Loading...</div>

  <div id="save-form" class="hidden">
    <div class="mb-3">
      <label class="text-xs text-gray-500">Title</label>
      <input id="title" class="w-full px-2 py-1.5 border rounded text-sm" />
    </div>
    <div class="mb-3">
      <label class="text-xs text-gray-500">Tags</label>
      <div id="tag-list" class="flex flex-wrap gap-1 mb-1"></div>
    </div>
    <div class="mb-3">
      <label class="text-xs text-gray-500">Collection</label>
      <select id="collection" class="w-full px-2 py-1.5 border rounded text-sm">
        <option value="">None</option>
      </select>
    </div>
    <button id="save-btn" class="w-full py-2 bg-blue-600 text-white rounded text-sm font-medium">
      Save to LinkVault
    </button>
  </div>

  <div id="already-saved" class="hidden text-center py-4">
    <div class="text-green-600 text-lg mb-1">Already saved</div>
    <p class="text-sm text-gray-500">This page is in your LinkVault.</p>
  </div>

  <div id="setup" class="hidden">
    <p class="text-sm text-gray-600 mb-3">Enter your API key to get started.</p>
    <input id="api-key" type="password" placeholder="Your API key"
      class="w-full px-2 py-1.5 border rounded text-sm mb-2" />
    <button id="save-key" class="w-full py-2 bg-blue-600 text-white rounded text-sm">
      Save Key
    </button>
  </div>
</div>

Add bookmark import from Chrome and Firefox:

1. Settings page (/dashboard/settings) section: "Import Bookmarks"
2. File upload: accept Chrome bookmarks export (HTML file) and Firefox export (JSON)
3. Parse the file client-side:
   - Chrome: parse the HTML file (DL/DT/A structure)
   - Firefox: parse the JSON export
4. Show preview: list of bookmarks to import with checkboxes
5. "Import Selected" button
6. Import in batches of 50 (avoid timeout)
7. Show progress bar during import
8. Auto-fetch metadata for imported links (queue in background)

function parseChromeBookmarks(html: string): ImportedBookmark[] {
  const parser = new DOMParser();
  const doc = parser.parseFromString(html, "text/html");
  const bookmarks: ImportedBookmark[] = [];

  const links = doc.querySelectorAll("a");
  links.forEach((link) => {
    const url = link.getAttribute("href");
    const title = link.textContent?.trim();
    const addDate = link.getAttribute("add_date");

    if (url && url.startsWith("http")) {
      bookmarks.push({
        url,
        title: title || url,
        createdAt: addDate ? new Date(parseInt(addDate) * 1000).toISOString() : new Date().toISOString(),
      });
    }
  });

  return bookmarks;
}

async function importBookmarks(bookmarks: ImportedBookmark[]) {
  const batchSize = 50;
  let imported = 0;

  for (let i = 0; i < bookmarks.length; i += batchSize) {
    const batch = bookmarks.slice(i, i + batchSize);

    await fetch("/api/links/import", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ links: batch }),
    });

    imported += batch.length;
    setProgress(Math.round((imported / bookmarks.length) * 100));
  }
}

Write tests:

1. API tests using Jest + supertest:
   - Auth: register via API key
   - Links: CRUD operations
   - Search: full-text search returns correct results
   - Tags: CRUD, filtering by tag
   - Rate limiting: verify 429 after 100 requests

2. E2E tests using Playwright:
   - Login with test credentials
   - Save a link via the "Add Link" dialog
   - Search for the saved link
   - Filter by tag
   - Delete the link

Use a test database (separate from development).

Final polish:

1. Loading states: skeleton loaders for link cards and sidebar
2. Error handling: toast notifications for save/delete/import errors
3. Empty states: "No links yet — save your first bookmark" with illustration
4. Keyboard shortcuts: / to focus search, n to open "Add Link" dialog
5. Mobile responsive: collapsible sidebar, stack cards vertically
6. SEO: meta tags, Open Graph image for landing page
7. Favicon and app icons
8. 404 page

Deploy to production:

1. Vercel deployment:
   - Create vercel.json with proper configuration
   - Set up environment variables
   - Configure custom domain

2. Supabase production database:
   - Run Prisma migrations on production database
   - Set up connection pooling

3. Monitoring:
   - Add Sentry error tracking (free tier)
   - Add Vercel Analytics (free)

4. Security:
   - Rate limiting on all API routes
   - CSRF protection
   - Input sanitization
   - SQL injection prevention (Prisma handles this)
   - XSS prevention (React handles this)

5. Performance:
   - Image optimization for favicons
   - API response caching (stale-while-revalidate)
   - Database query optimization (proper indexes)

Create a deployment checklist as a comment in vercel.json.

# 1. Push to GitHub
git add -A
git commit -m "LinkVault MVP — complete"
git push

# 2. Connect to Vercel
vercel link

# 3. Set environment variables
vercel env add DATABASE_URL
vercel env add NEXTAUTH_SECRET
vercel env add GITHUB_CLIENT_ID
vercel env add GITHUB_CLIENT_SECRET
vercel env add GOOGLE_CLIENT_ID
vercel env add GOOGLE_CLIENT_SECRET
vercel env add SENTRY_DSN

# 4. Deploy
vercel --prod

# 5. Run migrations on production
DATABASE_URL="production-url" npx prisma migrate deploy

# 6. Set custom domain
vercel domains add linkvault.app

generator client {
  provider      = "prisma-client-js"
  binaryTargets = ["native", "rhel-openssl-3.0.x"]
}

I want to build [product description].
Help me plan:
1. Tech stack recommendation (optimize for speed of development + free hosting)
2. Database schema
3. Feature priority list (what to build first for MVP)
4. Pages/routes needed
5. Third-party integrations

Create [app name] with [framework].

Phase 1 — Foundation:
1. Landing page with [key sections]
2. Auth with [provider] — [auth methods]
3. Database schema: [list all models with fields]
4. Middleware: protect [routes]
5. Basic shell for [main page]

Add [feature name]:

1. [Specific requirement with details]
2. [API endpoint with request/response shape]
3. [UI component with layout description]
4. [Edge cases to handle]

Follow the existing patterns in the codebase.

Final polish:
1. Loading states: [where]
2. Error handling: [what kind]
3. Empty states: [which pages]
4. Keyboard shortcuts: [which ones]
5. Mobile responsive: [what needs fixing]
6. SEO: [meta tags, OG images]

Deploy to production:
1. [Hosting platform] configuration
2. Database migration on production
3. Environment variables
4. Monitoring: [error tracking, analytics]
5. Security: [rate limiting, CSRF, etc.]
6. Performance: [caching, optimization]