​

Card Types

​

Available Card Types

export const cardTypes = [
  "text",
  "link",
  "image",
  "video",
  "audio",
  "document",
  "palette",
  "quote",
] as const;

​

Text Cards

​

Properties

• content: The main text content
• tags: User-defined tags
• notes: Additional annotations
• aiTags: Auto-generated topic tags
• aiSummary: AI-generated summary (for longer text)

​

Use Cases

• Quick notes and ideas
• Code snippets
• Quotes and excerpts
• Meeting notes
• Brain dumps

​

Link Cards

​

Properties

• url: The web address
• content: User notes about the link
• metadata.linkPreview: Rich preview data
  • title: Page title
  • description: Meta description
  • imageUrl: Social preview image
  • faviconUrl: Site favicon
  • siteName: Publisher name
  • author: Content author
  • publishedAt: Publication date
• metadata.linkCategory: Classified category
  • category: One of the link categories (article, video, product, etc.)
  • confidence: Classification confidence score
  • detectedProvider: Platform detection (YouTube, GitHub, Medium, etc.)

​

Link Categories

• Article: Blog posts, news articles, documentation
• Video: YouTube, Vimeo, streaming content
• Product: E-commerce, SaaS products, tools
• Repository: GitHub repos, code samples
• Design: Dribbble, Behance, design inspiration
• Social: Twitter threads, LinkedIn posts
• Tool: Web apps, utilities, services

​

Metadata Fetching

1. URL is validated and stored
2. Link metadata workflow is triggered
3. Page is fetched and parsed for Open Graph/meta tags
4. Preview image is cached in Convex storage
5. Category is classified using AI
6. Structured data is extracted (for supported providers)

// Example link metadata
metadata: {
  linkPreview: {
    status: "success",
    url: "https://example.com/article",
    finalUrl: "https://example.com/article",
    title: "How to Build with Convex",
    description: "A comprehensive guide...",
    imageUrl: "https://cdn.example.com/preview.jpg",
    imageStorageId: "kg2h4jk3h2k4h...",
    faviconUrl: "https://example.com/favicon.ico",
    siteName: "Tech Blog",
    author: "Jane Developer",
    publishedAt: "2024-01-15",
    fetchedAt: 1705334400000
  },
  linkCategory: {
    category: "article",
    confidence: 0.92,
    detectedProvider: "Medium",
    fetchedAt: 1705334400000,
    sourceUrl: "https://example.com/article"
  }
}

​

Image Cards

​

Properties

• fileId: Reference to uploaded image file
• thumbnailId: Generated thumbnail (for large images)
• content: User description or caption
• fileMetadata: Image details
  • width: Image width in pixels
  • height: Image height in pixels
  • fileSize: File size in bytes
  • fileName: Original filename
  • mimeType: Image format (image/png, image/jpeg, etc.)
• colors: Extracted color palette
• colorHexes: Array of hex color codes
• colorHues: Categorized hues (red, blue, green, etc.)
• visualStyles: Style classifications (minimal, vibrant, photographic, etc.)
• aiTags: AI-generated content tags
• aiSummary: Description of image content

​

Supported Formats

• PNG (.png)
• JPEG (.jpg, .jpeg)
• GIF (.gif)
• WebP (.webp)
• SVG (.svg) - rendered to bitmap for palette extraction

​

Color Palette Extraction

colors: [
  {
    hex: "#8B7355",
    name: "Almond",
    rgb: { r: 139, g: 115, b: 85 },
    hsl: { h: 33, s: 24, l: 44 }
  },
  {
    hex: "#D4A574",
    rgb: { r: 212, g: 165, b: 116 },
    hsl: { h: 31, s: 53, l: 64 }
  }
]

​

Visual Styles

• abstract - Abstract art and patterns
• cinematic - Film-like, wide shots, dramatic
• dark - Low-key lighting, dark tones
• illustrative - Drawings, cartoons, illustrations
• minimal - Simple, clean, negative space
• monochrome - Black and white, grayscale
• moody - Atmospheric, dramatic lighting
• pastel - Soft, muted colors
• photographic - Realistic photography
• retro - Vintage aesthetic, synthwave
• surreal - Dreamlike, unusual compositions
• vintage - Old, aged appearance
• vibrant - Bright, saturated colors

​

Video Cards

​

Properties

• fileId: Reference to uploaded video file
• thumbnailId: Auto-generated video thumbnail
• content: User description or caption
• fileMetadata: Video details
  • duration: Length in seconds
  • width: Video width in pixels
  • height: Video height in pixels
  • fileSize: File size in bytes
  • fileName: Original filename
  • mimeType: Video format (video/mp4, video/webm, etc.)
• aiTranscript: Speech-to-text transcription
• aiSummary: AI-generated content summary
• aiTags: Auto-extracted topic tags

​

Supported Formats

• MP4 (.mp4)
• WebM (.webm)
• MOV (.mov)
• AVI (.avi)

​

Processing Pipeline

1. Video file is uploaded to Convex storage
2. Thumbnail is generated from first frame or middle frame
3. Audio is extracted and transcribed (if speech detected)
4. AI generates summary based on transcript and visual content
5. Topics are auto-tagged

​

Audio Cards

​

Properties

• fileId: Reference to uploaded audio file
• content: User description or title
• fileMetadata: Audio details
  • duration: Length in seconds
  • fileSize: File size in bytes
  • fileName: Original filename
  • mimeType: Audio format (audio/mp3, audio/wav, etc.)
  • recordingTimestamp: When recording was made (optional)
• aiTranscript: Full speech-to-text transcription
• aiSummary: AI-generated summary of content
• aiTags: Auto-extracted topic tags

​

Supported Formats

• MP3 (.mp3)
• WAV (.wav)
• OGG (.ogg)
• M4A (.m4a)
• FLAC (.flac)

​

Transcription

• Speaker detection (if multiple speakers)
• Timestamp markers
• High accuracy speech-to-text
• Searchable transcript content

aiTranscript: `[00:00] Welcome to the podcast. Today we're discussing...
[01:32] Our guest shares insights about...
[05:45] Key takeaway: Always validate your assumptions...`

​

Document Cards

​

Properties

• fileId: Reference to uploaded document
• thumbnailId: Preview thumbnail (first page)
• content: User description or summary
• fileMetadata: Document details
  • fileSize: File size in bytes
  • fileName: Original filename
  • mimeType: Document format
• aiSummary: AI-generated document summary
• aiTags: Auto-extracted topic tags

​

Supported Formats

• PDF (.pdf)
• Microsoft Word (.doc, .docx)
• Microsoft PowerPoint (.ppt, .pptx)
• Text files (.txt, .md)

​

Processing

1. Document is uploaded to Convex storage
2. First page/slide is rendered as thumbnail
3. Text content is extracted
4. AI analyzes and summarizes key points
5. Topics are auto-tagged

​

Palette Cards

​

Properties

• content: Palette name or description
• colors: Array of color objects with full details
• colorHexes: Quick array of hex codes
• colorHues: Categorized hue buckets

​

Color Structure

colors: [
  {
    hex: "#8B7355",
    name: "Almond",
    rgb: { r: 139, g: 115, b: 85 },
    hsl: { h: 33, s: 24, l: 44 }
  },
  {
    hex: "#D4A574",
    name: "Tan",
    rgb: { r: 212, g: 165, b: 116 },
    hsl: { h: 31, s: 53, l: 64 }
  }
]

​

Color Hue Buckets

• red
• orange
• yellow
• green
• teal
• cyan
• blue
• purple
• pink
• brown
• neutral (grays, blacks, whites)

​

Quote Cards

​

Properties

• content: The quote text
• notes: Attribution (author, source, context)
• tags: Topic tags
• aiTags: Auto-extracted themes and topics

​

Formatting

• Proper quotation marks
• Attribution styling
• Blockquote rendering
• Source links (if applicable)

​

Use Cases

• Book quotes and highlights
• Inspirational sayings
• Notable excerpts from articles
• Customer testimonials
• Interview sound bites

​

Type Classification

// Classification workflow
classification: {
  type: "image",
  confidence: 0.95,
  needsLinkMetadata: false,
  shouldCategorize: false,
  shouldGenerateMetadata: true,
  shouldGenerateRenderables: true
}

• File extensions and MIME types
• URL patterns
• Content structure
• Metadata hints

​

Type-Specific Indexes

.index("by_user_type", ["userId", "type"])
.index("by_user_type_deleted", ["userId", "type", "isDeleted"])

// Get all image cards
const images = await ctx.db
  .query("cards")
  .withIndex("by_user_type_deleted", (q) =>
    q.eq("userId", userId)
     .eq("type", "image")
     .eq("isDeleted", undefined)
  )
  .collect();

​

Next Steps