slop-explainer-bsky-folders.md
edited
1I'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.
2
3Read [./bskyembed/package.json](./bskyembed/package.json)
4
5Read [./bskylink/package.json](./bskylink/package.json)
6
7Read [./bskyogcard/package.json](./bskyogcard/package.json)
8
9Read [./bskyweb/README.md](./bskyweb/README.md)
10
11I'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.
12
13Read [./bskylink/src/index.ts](./bskylink/src/index.ts)
14
15Read [./bskylink/src/routes/index.ts](./bskylink/src/routes/index.ts)
16
17Searched for files matching `**/bskyembed`, 43 matches
18
19Read [./bskyembed/README.md)](./bskyembed/README.md)
20
21Here's a concise explanation of each folder/package, what it does, how it fits into the repo, and how to run or inspect it.
22
23bskyembed
24- 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.
25- Key tech: Preact, Vite, Tailwind, TypeScript.
26- Where to look: src (components: embed.tsx, post.tsx, etc.), embed.ts (the snippet), post.html/test.html.
27- How to run:
28 - Dev server: cd bskyembed && yarn && yarn dev
29 - Build: yarn build (also `yarn dev-snippet` to build/test snippet)
30- Typical use: embed a Bluesky post into other sites or the web UI; used to render posts in a lightweight client-side widget.
31
32bskylink
33- 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).
34- Key tech: Node/Express, Kysely/pg for storage, i18n, a small HTTP server.
35- Where to look: src — main entry index.ts, routes in routes (`redirect`, `shortLink`, `createShortLink`, `siteAssociation`, `health`), config/context/db code.
36- How to run:
37 - Build: `yarn build` (or run directly in dev via ts-node in tests)
38 - The service exposes routes like `/redirect`, `/:linkId`, `/.well-known/apple-app-site-association`, and a POST `/link` to create links.
39- 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).
40
41bskyogcard
42- Purpose: An Open Graph (OG) card / image generator for Bluesky posts. It renders dynamic OG images (for social shares, link previews) server-side.
43- Key tech: Node + ts-node, Satori (JS-to-SVG/Canvas), resvg (to rasterize), React for layout, Twemoji, fonts and assets.
44- Where to look: src (server entry, rendering logic), `bskyogcard/assets/` (fonts/images), `scripts/install-fonts.ts`.
45- How to run:
46 - Dev start: `yarn start` (runs `src/bin.ts`)
47 - Build: `yarn build` (compiles + copies assets)
48 - It exposes endpoints that return OG images (SVG/PNG) for posts.
49- Typical use: generate on-demand OG images for sharing links so social platforms show rich previews.
50
51bskyweb
52- 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.
53- 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.
54- Where to look: bskyweb — README.md (how to build/run), `static/`, `templates/`, `cmd/` (Go server), `embedr-static`/`embedr-templates` for embed integration.
55- How to run:
56 - Build SPA: at repo root `yarn build-web` (per top-level README)
57 - Run Go daemon: `cd bskyweb && go run ./cmd/bskyweb serve` or `go build -o bskyweb ./cmd/bskyweb/ && ./bskyweb`
58- Typical use: serves the main web app, handles routing, and can integrate embeddable content and OG cards for the website.
59
60Quick pointers / next steps
61- If you want to trace how a post becomes an embed/OG image on the public site, check:
62 - Where the site links to the embed snippet: bskyweb templates/static pages → references to bskyembed snippet or bskyogcard endpoints.
63 - Link redirects and short URLs: inspect redirect.ts and `shortLink.ts`.
64- 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.
65
66Would you like a short diagram of how requests flow between these components (web → bskylink → bskyembed/bskyogcard), or commands to run any of them locally?
67
68I'll add a one-item todo for producing the diagram (in-progress), then show the diagram and explanation, and then mark the todo completed.
69
70## Diagram — how requests flow between bskyweb, bskylink, bskyembed, and bskyogcard
71
72### High-level summary
73- bskyweb: the main web frontend and server that serves pages and may reference embeds / OG images.
74- bskylink: small link/redirect service (short links, app site association, controlled redirects).
75- bskyembed: client-side embeddable snippet that renders Bluesky posts in third-party pages or the web UI.
76- bskyogcard: server-side image/OG generator that produces share images (SVG/PNG) for posts.
77
78### ASCII sequence (common flows)
79
801) User opens a post on the web (regular browsing)
81Browser -> bskyweb (Go / static SPA)
82bskyweb may:
83 - render the SPA (bundle.web.js)
84 - include a client-side embed snippet or references to OG images for social previews
85
862) Social / platform requests an OG image for a post (link preview)
87Platform crawler -> bskyweb (or directly) -> bskyogcard
88bskyogcard -> fetches post data (via repo API / internal service) -> renders OG image -> returns image (SVG/PNG) to crawler
89Crawler shows preview with image returned by bskyogcard
90
913) Short link / redirect
92Browser (or embed) -> short URL served by bskylink -> bskylink resolves -> redirects to canonical bskyweb or post URL
93bskylink may also provide endpoints for creating short links (POST /link)
94
954) External site embeds a post via the embed snippet
96Third-party page includes bskyembed snippet -> bskyembed fetches post content (via API) -> renders native-like post UI inside the host page
97bskyembed may reference bskyogcard for images or bskylink for shortened links
98
99### Mermaid-style flow (readable visual)
100You can copy this into a Mermaid viewer if you like:
101
102```mermaid
103sequenceDiagram
104 participant U as User (Browser)
105 participant BW as bskyweb (Go + SPA)
106 participant BL as bskylink (shortlink/redirect)
107 participant BE as bskyembed (embed snippet)
108 participant OG as bskyogcard (OG image server)
109 participant API as Data/API (post content)
110
111 U->>BW: Request page /post/…
112 BW-->>U: Serve page (bundle + HTML)
113 note right of BW: Page may reference embed/OG/short-links
114
115 U->>BL: Follow short link (/:id)
116 BL-->>U: 302 -> canonical post URL (bskyweb)
117
118 U->>BE: Host page includes embed snippet (third-party page)
119 BE->>API: Fetch post content
120 API-->>BE: Post JSON
121 BE-->>HostPage: Render embed
122
123 U->>BW: Social crawler requests URL
124 BW->>OG: Request OG image for post
125 OG->>API: Fetch post content
126 API-->>OG: Post JSON
127 OG-->>BW: Return image
128 BW-->>Crawler: Serve OG image (or redirect to OG endpoint)
129```
130
131### Typical endpoints / places to inspect in repo
132- bskyweb
133 - SPA bundle and templates: static, templates, cmd
134 - Serve: `go run ./cmd/bskyweb serve`
135- bskylink
136 - Routes: routes (redirect, shortLink, createShortLink, siteAssociation)
137 - Main service: index.ts
138- bskyembed
139 - Snippet and components: snippet and src (embed.tsx, post.tsx)
140 - Dev server / build: README.md
141- bskyogcard
142 - OG generation: src (uses Satori/resvg/react)
143 - Entry/daemon: bin.ts
144
145### Short examples of how the pieces interact (concrete)
146- When someone shares a post link on Twitter:
147 - 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).
148 - bskyogcard produces the image on-demand using the post content and returns PNG/SVG. Twitter shows a rich preview.
149
150- When an external site wants to show an embed:
151 - They include a script/snippet from bskyembed or copy the embed `<iframe>`/snippet.
152 - The snippet calls the Bluesky API (or an internal proxy) for post data and renders it inside the page.
153
154- When a mobile app wants universal link support:
155 - The site association endpoints provided by bskylink (or bskyweb) help iOS/Android map web links to the app.
156
157### Quick diagram notes / next steps
158- If you want, I can:
159 - Produce a PNG/SVG version of the Mermaid diagram.
160 - Generate an endpoint map (list of exact routes used by each component).
161 - Trace a concrete request top-to-bottom for a specific post id (I can show sample curl requests and returned JSON/images).