Link Loom

Link Loom is an intelligent bookmark organization tool that uses AI to cluster and categorize your chaotic browser bookmarks into a structured, easy-to-navigate hierarchy.

🚀 Features

• AI-Powered Clustering: Automatically analyzes your bookmarks and groups them by topic using K-Means clustering and OpenAI embeddings.
• Smart Organization: Creates a logical folder structure for your links.
• Chrome Extension: A user-friendly browser extension to manage the weaving process.
  • Visual Progress: Real-time feedback on the organization process.
  • Preview: View the proposed structure before applying changes.
  • Dark/Light Mode: Premium design with frosted glass effects.
• Modern Stack: Built with a robust monorepo architecture.

🛠️ Tech Stack

This project is a monorepo managed by Turborepo and pnpm.

Apps

• apps/extension: Chrome Extension built with React, Vite, and CRXJS.
• apps/backend: Fastify API for bookmark ingestion, embedding (OpenAI), and clustering (ml-kmeans). Uses Supabase (Postgres) for storage and SQS/Lambda for production queues.
• apps/web: Next.js application (Marketing/Dashboard).

Packages

• packages/ui: Shared UI components.
• packages/tsconfig: Shared TypeScript configurations.
• packages/shared: Shared utilities and types.

📋 Prerequisites

• Node.js (>= 18)
• pnpm (>= 8)
• Docker (for local Supabase)
• Supabase CLI
• OpenAI API Key

🏁 Getting Started

1. Clone the repository

   git clone <repo-url>
   cd link-loom

2. Install dependencies

   pnpm install

3. Environment Setup

   • Copy .env.example to .env.local in apps/web, apps/backend, and apps/extension.
   • Use npx supabase status after starting Supabase to copy the local API URL, anon key, service role key, and DB URL into those files.
   • apps/backend also needs OPENAI_API_KEY for AI processing.

4. Start Infrastructure

   • Ensure Docker is running.
   • Start local Supabase: npx supabase start
   • Bookmark processing runs inline in local development; production should set QUEUE_DRIVER=sqs and use SQS-triggered Lambda workers.
   • For web login/signup work only, Supabase plus pnpm --filter web dev is enough.

5. Run Development Server

   pnpm dev

   This command starts all applications in parallel using Turbo.

6. Production Lambda Deploy

   • Production deploys use apps/*/.env.production as the source of truth.
   • The root Makefile maps those values into Terraform TF_VAR_* variables.
   • Check the mapping without printing secrets:

     make tf-env-print

   • Validate and deploy the Lambda/SQS backend:

     make tf-check
     make tf-plan
     make deploy
     make smoke-prod

   • There is no Redis/ElastiCache in production; SQS-triggered Lambda workers process jobs.

7. Stripe Local Development To test premium features locally, you need to forward Stripe webhooks to your local environment.

   • Set STRIPE_SECRET_KEY, STRIPE_PRICE_ID_PRO, STRIPE_WEBHOOK_SECRET, and NEXT_PUBLIC_SITE_URL=http://localhost:3000 in apps/web/.env.local.
   • Match Stripe modes: sk_test_... must use a test-mode price_...; sk_live_... must use a live-mode price_....
   • Use STRIPE_CHECKOUT_MODE=payment for the one-time lifetime Pro plan. Use subscription only with a recurring Stripe Price.
   • Install the Stripe CLI.
   • Log in to your Stripe account:

     stripe login

   • Start forwarding webhook events to your local Next.js API:

     stripe listen --forward-to localhost:3000/api/webhooks/stripe

   • Copy the generated webhook secret (whsec_...) and add it to your apps/web/.env.local as STRIPE_WEBHOOK_SECRET.
   • In the web app, test upgrades from http://localhost:3000/dashboard/billing. The dashboard uses /api/checkout and the current Supabase web session; the extension signup flow uses /api/create-checkout-session with its Supabase bearer token.
   • In Stripe test mode, complete Checkout with card 4242 4242 4242 4242, any future expiry, any CVC, and any ZIP.

🧩 Extension Development

To load the extension in Chrome:

1. Run the build or dev command:

   # For popup/web development
   pnpm dev
   
   # Build the Chrome extension against local Supabase/web/backend envs
   pnpm --filter extension build:local
   
   # OR build the production extension bundle
   pnpm build

   apps/extension/.env.local is for local development, while apps/extension/.env.production is used by the normal production build. If the unpacked extension should log into local Supabase users, load a bundle built with pnpm --filter extension build:local.

2. Open Chrome and navigate to chrome://extensions/.

3. Enable Developer mode (top right).

4. Click Load unpacked.

5. Select the apps/extension/dist folder.

Note: Do not load the apps/extension root folder; you must load the dist folder generated by the build.

🏗️ Project Structure

link-loom/
├── apps/
│   ├── backend/    # Fastify API & Job Workers
│   ├── extension/  # Chrome Extension (React/Vite)
│   └── web/        # Next.js Frontend
├── packages/
│   ├── tsconfig/   # Shared TS Config
│   ├── ui/         # Shared Components
│   └── shared/     # Shared Logic
├── turbo.json      # Turborepo Config
└── package.json    # Root Config

🧪 Testing

Link Loom uses a combination of Vitest (for backend unit tests) and Playwright (for frontend E2E tests).

Backend Tests

The backend uses Vitest to test the AI background workers (ingestion, enrichment, embedding, and clustering queues).

cd apps/backend
pnpm run test

Web E2E Tests

The web application uses Playwright to perform end-to-end tests on critical user paths like the marketing pages.

cd apps/web
pnpm run test:e2e

To run the Playwright tests in interactive UI mode:

cd apps/web
pnpm run test:e2e:ui

📜 Scripts

• pnpm build: Build all apps and packages.
• pnpm dev: Start all apps in development mode.
• pnpm lint: Lint all code.
• pnpm format: Format code with Prettier.