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](./bskyembed/package.json) Read [./bskylink/package.json](./bskylink/package.json) Read [./bskyogcard/package.json](./bskyogcard/package.json) Read [./bskyweb/README.md](./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](./bskylink/src/index.ts) Read [./bskylink/src/routes/index.ts](./bskylink/src/routes/index.ts) Searched for files matching `**/bskyembed`, 43 matches Read [./bskyembed/README.md)](./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: ```mermaid 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 `