# vvvasavii/woven architecture

> Architecture diagram of the GitHub repository vvvasavii/woven, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vvvasavii/woven
- Repository: https://github.com/vvvasavii/woven

## Overview

Woven is a personal bookmark and knowledge library. Users create bookmarks from generated or edited link previews, organize them into collections, add notes and attachments, favorite resources, and search within dashboard, bookmark, collection, or favorite views. Client pages call Next.js route handlers; handlers authenticate and authorize through the user mapping, then use Prisma for persistent records. The preview, attachments, image uploads, and contextual search are distinct capabilities. Relationships below follow shown excerpts or README statements; links for unsampled page/API behavior rely on documented capabilities and are marked dashed where not directly evidenced.

Main entry points: [`app/bookmarks/page.tsx`](https://github.com/vvvasavii/woven/blob/main/app/bookmarks/page.tsx) (Bookmarks page), [`lib/auth.ts`](https://github.com/vvvasavii/woven/blob/main/lib/auth.ts) (User identity mapping), [`app/dashboard/page.tsx`](https://github.com/vvvasavii/woven/blob/main/app/dashboard/page.tsx) (Dashboard), [`app/api/bookmarks/route.ts`](https://github.com/vvvasavii/woven/blob/main/app/api/bookmarks/route.ts) (Bookmark handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_bookmark_page["Bookmarks page<br/>[page.tsx]"]
  node_collection_page["Collections page<br/>[page.tsx]"]
  node_collection_detail["Collection detail<br/>[page.tsx]"]
  node_favorites_page["Favorites page<br/>[page.tsx]"]
  node_bookmark_dialog["Bookmark detail"]
  node_create_bookmark["Create bookmark"]
  node_collection_dialogs["Collection dialogs"]
end

subgraph group_bookmark["Bookmarks and discovery"]
  node_bookmark_api["Bookmark handlers<br/>[route.ts]"]
  node_bookmark_item_api["Bookmark item handlers<br/>[route.ts]"]
  node_favorites_api["Favorites handler<br/>[route.ts]"]
  node_search_api["Search handler<br/>[route.ts]"]
  node_preview_api["Link preview<br/>[route.ts]"]
  node_bookmark_card["Bookmark card<br/>[BookmarkCard.tsx]"]
end

subgraph group_organization["Collections"]
  node_collections_api["Collection handlers<br/>[route.ts]"]
  node_collection_item_api["Collection item handlers<br/>[route.ts]"]
  node_bookmark_collections_api["Collection membership<br/>[route.ts]"]
  node_attachments_api["Attachment handlers<br/>[route.ts]"]
  node_attachment_item_api["Attachment item handler<br/>[route.ts]"]
  node_attachment_upload["Attachment upload"]
  node_collection_images["Collection image upload"]
end

subgraph group_backend["Application backend"]
  node_auth["User identity mapping<br/>[auth.ts]"]
  node_database[("PostgreSQL")]
  node_prisma["Prisma client<br/>[prisma.ts]"]
end

subgraph group_integrations["Identity and services"]
  node_clerk{{"Clerk"}}
  node_cloudinary{{"Cloudinary"}}
  node_cloudinary_sign["Cloudinary signing<br/>[route.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_dashboard
node_user -->|"uses"| node_bookmark_page
node_user -->|"uses"| node_collection_page
node_user -.->|"uses"| node_collection_detail
node_user -.->|"uses"| node_favorites_page
node_dashboard -->|"fetches"| node_bookmark_api
node_dashboard -->|"fetches"| node_collections_api
node_bookmark_page -->|"fetches"| node_bookmark_api
node_collection_page -->|"fetches"| node_collections_api
node_dashboard -.->|"opens"| node_create_bookmark
node_bookmark_page -.->|"opens"| node_create_bookmark
node_bookmark_page -.->|"opens"| node_bookmark_dialog
node_collection_page -.->|"opens"| node_collection_dialogs
node_bookmark_page -.->|"renders"| node_bookmark_card
node_favorites_page -.->|"renders"| node_bookmark_card
node_bookmark_dialog -->|"renders"| node_attachment_upload
node_bookmark_card -->|"updates favorite"| node_bookmark_item_api
node_create_bookmark -.->|"requests preview"| node_preview_api
node_create_bookmark -.->|"creates bookmark"| node_bookmark_api
node_bookmark_api -->|"identifies user"| node_auth
node_collections_api -->|"identifies user"| node_auth
node_collection_item_api -->|"identifies user"| node_auth
node_bookmark_api -->|"queries"| node_prisma
node_collections_api -->|"queries"| node_prisma
node_collection_item_api -->|"queries"| node_prisma
node_auth -->|"authenticates"| node_clerk
node_auth -->|"maps user"| node_prisma
node_prisma -->|"reads and writes"| node_database
node_preview_api -.->|"returns metadata"| node_user
node_favorites_page -.->|"loads favorites"| node_favorites_api
node_dashboard -.->|"searches"| node_search_api
node_bookmark_page -.->|"searches"| node_search_api
node_collection_page -.->|"searches"| node_search_api
node_favorites_page -.->|"searches"| node_search_api
node_collection_detail -.->|"loads collection"| node_collection_item_api
node_collection_detail -.->|"manages membership"| node_bookmark_collections_api
node_bookmark_dialog -.->|"manages attachments"| node_attachments_api
node_attachment_upload -.->|"uploads"| node_attachments_api
node_attachment_item_api -.->|"deletes media"| node_cloudinary
node_collection_images -.->|"requests signature"| node_cloudinary_sign
node_cloudinary_sign -->|"identifies user"| node_auth
node_cloudinary_sign -.->|"signs upload"| node_cloudinary

click node_dashboard "https://github.com/vvvasavii/woven/blob/main/app/dashboard/page.tsx"
click node_bookmark_page "https://github.com/vvvasavii/woven/blob/main/app/bookmarks/page.tsx"
click node_collection_page "https://github.com/vvvasavii/woven/blob/main/app/collections/page.tsx"
click node_collection_detail "https://github.com/vvvasavii/woven/blob/main/app/collections/%5Bid%5D/page.tsx"
click node_favorites_page "https://github.com/vvvasavii/woven/blob/main/app/favorites/page.tsx"
click node_bookmark_dialog "https://github.com/vvvasavii/woven/blob/main/components/dashboard/BookmarkDetailDialog.tsx"
click node_create_bookmark "https://github.com/vvvasavii/woven/blob/main/components/dashboard/CreateBookmarkDialog.tsx"
click node_collection_dialogs "https://github.com/vvvasavii/woven/blob/main/components/collections/CreateCollectionDialog.tsx"
click node_bookmark_api "https://github.com/vvvasavii/woven/blob/main/app/api/bookmarks/route.ts"
click node_bookmark_item_api "https://github.com/vvvasavii/woven/blob/main/app/api/bookmarks/%5Bid%5D/route.ts"
click node_favorites_api "https://github.com/vvvasavii/woven/blob/main/app/api/favorites/route.ts"
click node_search_api "https://github.com/vvvasavii/woven/blob/main/app/api/search/route.ts"
click node_preview_api "https://github.com/vvvasavii/woven/blob/main/app/api/link-preview/route.ts"
click node_bookmark_card "https://github.com/vvvasavii/woven/blob/main/components/dashboard/BookmarkCard.tsx"
click node_collections_api "https://github.com/vvvasavii/woven/blob/main/app/api/collections/route.ts"
click node_collection_item_api "https://github.com/vvvasavii/woven/blob/main/app/api/collections/%5Bid%5D/route.ts"
click node_bookmark_collections_api "https://github.com/vvvasavii/woven/blob/main/app/api/bookmarks/%5Bid%5D/collections/route.ts"
click node_attachments_api "https://github.com/vvvasavii/woven/blob/main/app/api/bookmarks/%5Bid%5D/attachments/route.ts"
click node_attachment_item_api "https://github.com/vvvasavii/woven/blob/main/app/api/bookmarks/%5Bid%5D/attachments/%5BattachmentId%5D/route.ts"
click node_attachment_upload "https://github.com/vvvasavii/woven/blob/main/components/attachments/AttachmentUpload.tsx"
click node_collection_images "https://github.com/vvvasavii/woven/blob/main/components/collections/CollectionImageUpload.tsx"
click node_auth "https://github.com/vvvasavii/woven/blob/main/lib/auth.ts"
click node_prisma "https://github.com/vvvasavii/woven/blob/main/lib/prisma.ts"
click node_cloudinary_sign "https://github.com/vvvasavii/woven/blob/main/app/api/cloudinary/sign/route.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_bookmark_page,node_collection_page,node_collection_detail,node_favorites_page,node_bookmark_dialog,node_create_bookmark,node_collection_dialogs,node_user toneBlue
class node_bookmark_api,node_bookmark_item_api,node_favorites_api,node_search_api,node_preview_api,node_bookmark_card toneAmber
class node_collections_api,node_collection_item_api,node_bookmark_collections_api,node_attachments_api,node_attachment_item_api,node_attachment_upload,node_collection_images toneMint
class node_auth,node_database,node_prisma toneRose
class node_clerk,node_cloudinary,node_cloudinary_sign toneIndigo
```

## Components

### User experience

- [Dashboard](https://github.com/vvvasavii/woven/blob/main/app/dashboard/page.tsx): `app/dashboard/page.tsx`
- [Bookmarks page](https://github.com/vvvasavii/woven/blob/main/app/bookmarks/page.tsx): `app/bookmarks/page.tsx`
- [Collections page](https://github.com/vvvasavii/woven/blob/main/app/collections/page.tsx): `app/collections/page.tsx`
- [Collection detail](https://github.com/vvvasavii/woven/blob/main/app/collections/%5Bid%5D/page.tsx): `app/collections/[id]/page.tsx`
- [Favorites page](https://github.com/vvvasavii/woven/blob/main/app/favorites/page.tsx): `app/favorites/page.tsx`
- [Bookmark detail](https://github.com/vvvasavii/woven/blob/main/components/dashboard/BookmarkDetailDialog.tsx): `components/dashboard/BookmarkDetailDialog.tsx`
- [Create bookmark](https://github.com/vvvasavii/woven/blob/main/components/dashboard/CreateBookmarkDialog.tsx): `components/dashboard/CreateBookmarkDialog.tsx`
- [Collection dialogs](https://github.com/vvvasavii/woven/blob/main/components/collections/CreateCollectionDialog.tsx): `components/collections/CreateCollectionDialog.tsx`

### Bookmarks and discovery

- [Bookmark handlers](https://github.com/vvvasavii/woven/blob/main/app/api/bookmarks/route.ts): `app/api/bookmarks/route.ts`
- [Bookmark item handlers](https://github.com/vvvasavii/woven/blob/main/app/api/bookmarks/%5Bid%5D/route.ts): `app/api/bookmarks/[id]/route.ts`
- [Favorites handler](https://github.com/vvvasavii/woven/blob/main/app/api/favorites/route.ts): `app/api/favorites/route.ts`
- [Search handler](https://github.com/vvvasavii/woven/blob/main/app/api/search/route.ts): `app/api/search/route.ts`
- [Link preview](https://github.com/vvvasavii/woven/blob/main/app/api/link-preview/route.ts): `app/api/link-preview/route.ts`
- [Bookmark card](https://github.com/vvvasavii/woven/blob/main/components/dashboard/BookmarkCard.tsx): `components/dashboard/BookmarkCard.tsx`

### Collections

- [Collection handlers](https://github.com/vvvasavii/woven/blob/main/app/api/collections/route.ts): `app/api/collections/route.ts`
- [Collection item handlers](https://github.com/vvvasavii/woven/blob/main/app/api/collections/%5Bid%5D/route.ts): `app/api/collections/[id]/route.ts`
- [Collection membership](https://github.com/vvvasavii/woven/blob/main/app/api/bookmarks/%5Bid%5D/collections/route.ts): `app/api/bookmarks/[id]/collections/route.ts`
- [Attachment handlers](https://github.com/vvvasavii/woven/blob/main/app/api/bookmarks/%5Bid%5D/attachments/route.ts): `app/api/bookmarks/[id]/attachments/route.ts`
- [Attachment item handler](https://github.com/vvvasavii/woven/blob/main/app/api/bookmarks/%5Bid%5D/attachments/%5BattachmentId%5D/route.ts): `app/api/bookmarks/[id]/attachments/[attachmentId]/route.ts`
- [Attachment upload](https://github.com/vvvasavii/woven/blob/main/components/attachments/AttachmentUpload.tsx): `components/attachments/AttachmentUpload.tsx`
- [Collection image upload](https://github.com/vvvasavii/woven/blob/main/components/collections/CollectionImageUpload.tsx): `components/collections/CollectionImageUpload.tsx`

### Application backend

- [User identity mapping](https://github.com/vvvasavii/woven/blob/main/lib/auth.ts): `lib/auth.ts`
- **PostgreSQL**
- [Prisma client](https://github.com/vvvasavii/woven/blob/main/lib/prisma.ts): `lib/prisma.ts`

### Identity and services

- **Clerk**
- **Cloudinary**
- [Cloudinary signing](https://github.com/vvvasavii/woven/blob/main/app/api/cloudinary/sign/route.ts): `app/api/cloudinary/sign/route.ts`

### Other components

- **User**

## Connections

- User → Dashboard: uses (evidence: `app/dashboard/page.tsx`)
- User → Bookmarks page: uses (evidence: `app/bookmarks/page.tsx`)
- User → Collections page: uses (evidence: `app/collections/page.tsx`)
- User → Collection detail: uses
- User → Favorites page: uses
- Dashboard → Bookmark handlers: fetches (evidence: `app/dashboard/page.tsx`)
- Dashboard → Collection handlers: fetches (evidence: `app/dashboard/page.tsx`)
- Bookmarks page → Bookmark handlers: fetches (evidence: `app/bookmarks/page.tsx`)
- Collections page → Collection handlers: fetches (evidence: `app/collections/page.tsx`)
- Dashboard → Create bookmark: opens (evidence: `app/dashboard/page.tsx`)
- Bookmarks page → Create bookmark: opens (evidence: `app/bookmarks/page.tsx`)
- Bookmarks page → Bookmark detail: opens (evidence: `app/bookmarks/page.tsx`)
- Collections page → Collection dialogs: opens (evidence: `app/collections/page.tsx`)
- Bookmarks page → Bookmark card: renders (evidence: `app/bookmarks/page.tsx`)
- Favorites page → Bookmark card: renders (evidence: `app/favorites/page.tsx`)
- Bookmark detail → Attachment upload: renders (evidence: `components/dashboard/BookmarkDetailDialog.tsx`)
- Bookmark card → Bookmark item handlers: updates favorite (evidence: `components/dashboard/BookmarkCard.tsx`)
- Create bookmark → Link preview: requests preview
- Create bookmark → Bookmark handlers: creates bookmark
- Bookmark handlers → User identity mapping: identifies user (evidence: `app/api/bookmarks/route.ts`)
- Collection handlers → User identity mapping: identifies user (evidence: `app/api/collections/route.ts`)
- Collection item handlers → User identity mapping: identifies user (evidence: `app/api/collections/[id]/route.ts`)
- Bookmark handlers → Prisma client: queries (evidence: `app/api/bookmarks/route.ts`)
- Collection handlers → Prisma client: queries (evidence: `app/api/collections/route.ts`)
- Collection item handlers → Prisma client: queries (evidence: `app/api/collections/[id]/route.ts`)
- User identity mapping → Clerk: authenticates (evidence: `lib/auth.ts`)
- User identity mapping → Prisma client: maps user (evidence: `lib/auth.ts`)
- Prisma client → PostgreSQL: reads and writes (evidence: `lib/prisma.ts`)
- Link preview → User: returns metadata
- Favorites page → Favorites handler: loads favorites
- Dashboard → Search handler: searches
- Bookmarks page → Search handler: searches
- Collections page → Search handler: searches
- Favorites page → Search handler: searches
- Collection detail → Collection item handlers: loads collection
- Collection detail → Collection membership: manages membership
- Bookmark detail → Attachment handlers: manages attachments
- Attachment upload → Attachment handlers: uploads
- Attachment item handler → Cloudinary: deletes media (evidence: `app/api/bookmarks/[id]/attachments/[attachmentId]/route.ts`)
- Collection image upload → Cloudinary signing: requests signature
- Cloudinary signing → User identity mapping: identifies user (evidence: `app/api/cloudinary/sign/route.ts`)
- Cloudinary signing → Cloudinary: signs upload
