Bluesky app fork with some witchin' additions 💫
witchsky.app
bluesky
fork
client
Add Witchsky-specific notes to CLAUDE.md
+19
+19
CLAUDE.md
+19
CLAUDE.md
···
804
804
| Query hooks | `src/state/queries/*.ts` |
805
805
| Session state | `src/state/session/index.tsx` |
806
806
| i18n setup | `src/locale/i18n.ts` |
807
+
808
+
## Witchsky-Specific Notes
809
+
810
+
Witchsky is a fork of the Bluesky Social app, but we don't control the backend (the Bluesky AppView or sometimes
811
+
AppServer). This means we have to go off-spec to implement features sometimes. We have a few tools at our disposal
812
+
for this:
813
+
814
+
- Adding extra fields to records in atproto is valid and will not fail validation. If necessary, we can add extra fields
815
+
to the data we send to the server, and these fields will be stored and returned by the server without issue. This is a
816
+
common way to add custom data without needing backend changes. Many AppView XRPC endpoints return a `record` field which
817
+
is just the original record. We can use `as any` on it and get extra fields in there without issue.
818
+
- Sometimes we need to go around the AppView. For instance, to see through blocks, we call getRecord on the AT uri of
819
+
the blocked post. This is a good pattern if the AppView doesn't return data we need.
820
+
- Sometimes we want to find all records that reference another record by AT uri. The AppView does this by consuming the
821
+
firehose server-side and maintaining an index. We have a generic index called Constellation. The API for this is
822
+
documented at https://constellation.microcosm.blue/ and we have a client for it in `src/state/queries/constellation.ts`
823
+
Constellation searches the firehose for anything that looks like a link, including AT uris in records, and maintains an
824
+
index of all the links it finds. We can query this index to find all records that link to a given AT uri. This is how we
825
+
implement custom verifiers, and you can see how it's queried at `src/state/queries/deer-verification.ts`.