I'll open each package's package.json / README to give an accurate summary of their purpose and how they relate to the app. I'll read four files and summarize.

Read ./bskyembed/package.json

Read ./bskylink/package.json

Read ./bskyogcard/package.json

Read ./bskyweb/README.md

I'll open each package's README or top-level files to extract more details (why/what/outcome): reading bskylink README and bskyembed README/snippet, bskyogcard README, and bskyweb main files. I'll run 4 quick reads.

Read ./bskylink/src/index.ts

Read ./bskylink/src/routes/index.ts

Searched for files matching **/bskyembed, 43 matches

Read ./bskyembed/README.md)

Here's a concise explanation of each folder/package, what it does, how it fits into the repo, and how to run or inspect it.

bskyembed

• Purpose: A small client-side embed UI/snippet used to render Bluesky posts on external webpages. It's a Preact/Vite app that produces an embeddable snippet and demo/test pages.
• Key tech: Preact, Vite, Tailwind, TypeScript.
• Where to look: src (components: embed.tsx, post.tsx, etc.), embed.ts (the snippet), post.html/test.html.
• How to run:
  • Dev server: cd bskyembed && yarn && yarn dev
  • Build: yarn build (also yarn dev-snippet to build/test snippet)
• Typical use: embed a Bluesky post into other sites or the web UI; used to render posts in a lightweight client-side widget.

bskylink

• Purpose: A small backend link/redirect/shortlink service for Bluesky URLs. It provides health checks, redirects, short-link creation, and site-association endpoints (e.g., Apple app site association).
• Key tech: Node/Express, Kysely/pg for storage, i18n, a small HTTP server.
• Where to look: src — main entry index.ts, routes in routes (redirect, shortLink, createShortLink, siteAssociation, health), config/context/db code.
• How to run:
  • Build: yarn build (or run directly in dev via ts-node in tests)
  • The service exposes routes like /redirect, /:linkId, /.well-known/apple-app-site-association, and a POST /link to create links.
• Typical use: used when you want short links or controlled redirects for Bluesky content (e.g., link previews, mobile app association, link shortening for embedding).

bskyogcard

• Purpose: An Open Graph (OG) card / image generator for Bluesky posts. It renders dynamic OG images (for social shares, link previews) server-side.
• Key tech: Node + ts-node, Satori (JS-to-SVG/Canvas), resvg (to rasterize), React for layout, Twemoji, fonts and assets.
• Where to look: src (server entry, rendering logic), bskyogcard/assets/ (fonts/images), scripts/install-fonts.ts.
• How to run:
  • Dev start: yarn start (runs src/bin.ts)
  • Build: yarn build (compiles + copies assets)
  • It exposes endpoints that return OG images (SVG/PNG) for posts.
• Typical use: generate on-demand OG images for sharing links so social platforms show rich previews.

bskyweb

• Purpose: The web frontend (and small Go daemon) for the Bluesky web UI served by this repo. It’s both the SPA/bundle and a server that can serve static files and handle dynamic routes.
• Key tech: frontend build produces bundle.web.js (top-level web build), Go for the server/daemon (under cmd), templates and static assets embedded by Go.
• Where to look: bskyweb — README.md (how to build/run), static/, templates/, cmd/ (Go server), embedr-static/embedr-templates for embed integration.
• How to run:
  • Build SPA: at repo root yarn build-web (per top-level README)
  • Run Go daemon: cd bskyweb && go run ./cmd/bskyweb serve or go build -o bskyweb ./cmd/bskyweb/ && ./bskyweb
• Typical use: serves the main web app, handles routing, and can integrate embeddable content and OG cards for the website.

Quick pointers / next steps

• If you want to trace how a post becomes an embed/OG image on the public site, check:
  • Where the site links to the embed snippet: bskyweb templates/static pages → references to bskyembed snippet or bskyogcard endpoints.
  • Link redirects and short URLs: inspect redirect.ts and shortLink.ts.
• If you want commands to run any of these locally, tell me which one and I’ll give a copy-pasteable fish-shell command sequence and example endpoints to hit.

Would you like a short diagram of how requests flow between these components (web → bskylink → bskyembed/bskyogcard), or commands to run any of them locally?

I'll add a one-item todo for producing the diagram (in-progress), then show the diagram and explanation, and then mark the todo completed.

Diagram — how requests flow between bskyweb, bskylink, bskyembed, and bskyogcard#

High-level summary#

• bskyweb: the main web frontend and server that serves pages and may reference embeds / OG images.
• bskylink: small link/redirect service (short links, app site association, controlled redirects).
• bskyembed: client-side embeddable snippet that renders Bluesky posts in third-party pages or the web UI.
• bskyogcard: server-side image/OG generator that produces share images (SVG/PNG) for posts.

ASCII sequence (common flows)#

1. User opens a post on the web (regular browsing) Browser -> bskyweb (Go / static SPA) bskyweb may:

• render the SPA (bundle.web.js)
• include a client-side embed snippet or references to OG images for social previews

2. Social / platform requests an OG image for a post (link preview) Platform crawler -> bskyweb (or directly) -> bskyogcard bskyogcard -> fetches post data (via repo API / internal service) -> renders OG image -> returns image (SVG/PNG) to crawler Crawler shows preview with image returned by bskyogcard

3. Short link / redirect Browser (or embed) -> short URL served by bskylink -> bskylink resolves -> redirects to canonical bskyweb or post URL bskylink may also provide endpoints for creating short links (POST /link)

4. External site embeds a post via the embed snippet Third-party page includes bskyembed snippet -> bskyembed fetches post content (via API) -> renders native-like post UI inside the host page bskyembed may reference bskyogcard for images or bskylink for shortened links

Mermaid-style flow (readable visual)#

You can copy this into a Mermaid viewer if you like:

sequenceDiagram
  participant U as User (Browser)
  participant BW as bskyweb (Go + SPA)
  participant BL as bskylink (shortlink/redirect)
  participant BE as bskyembed (embed snippet)
  participant OG as bskyogcard (OG image server)
  participant API as Data/API (post content)

  U->>BW: Request page /post/…
  BW-->>U: Serve page (bundle + HTML)
  note right of BW: Page may reference embed/OG/short-links

  U->>BL: Follow short link (/:id)
  BL-->>U: 302 -> canonical post URL (bskyweb)

  U->>BE: Host page includes embed snippet (third-party page)
  BE->>API: Fetch post content
  API-->>BE: Post JSON
  BE-->>HostPage: Render embed

  U->>BW: Social crawler requests URL
  BW->>OG: Request OG image for post
  OG->>API: Fetch post content
  API-->>OG: Post JSON
  OG-->>BW: Return image
  BW-->>Crawler: Serve OG image (or redirect to OG endpoint)

Typical endpoints / places to inspect in repo#

• bskyweb
  • SPA bundle and templates: static, templates, cmd
  • Serve: go run ./cmd/bskyweb serve
• bskylink
  • Routes: routes (redirect, shortLink, createShortLink, siteAssociation)
  • Main service: index.ts
• bskyembed
  • Snippet and components: snippet and src (embed.tsx, post.tsx)
  • Dev server / build: README.md
• bskyogcard
  • OG generation: src (uses Satori/resvg/react)
  • Entry/daemon: bin.ts

Short examples of how the pieces interact (concrete)#

• When someone shares a post link on Twitter:

  • Twitter fetches the Post URL. bskyweb (or a direct OG endpoint) responds with an HTML meta tag pointing to an OG image URL (or serves it directly).
  • bskyogcard produces the image on-demand using the post content and returns PNG/SVG. Twitter shows a rich preview.

• When an external site wants to show an embed:

  • They include a script/snippet from bskyembed or copy the embed <iframe>/snippet.
  • The snippet calls the Bluesky API (or an internal proxy) for post data and renders it inside the page.

• When a mobile app wants universal link support:

  • The site association endpoints provided by bskylink (or bskyweb) help iOS/Android map web links to the app.

Quick diagram notes / next steps#

• If you want, I can:
  • Produce a PNG/SVG version of the Mermaid diagram.
  • Generate an endpoint map (list of exact routes used by each component).
  • Trace a concrete request top-to-bottom for a specific post id (I can show sample curl requests and returned JSON/images).