your personal website on atproto - mirror
blento.app
flo-bit.dev
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5## Project Overview
6
7Blento is a Bluesky-powered customizable bento grid website builder. Users authenticate via ATProto OAuth and create draggable/resizable cards stored in their Bluesky PDS (Personal Data Server) using the `app.blento.card` collection.
8
9## Commands
10
11- `pnpm dev` - Start development server (Vite)
12- `pnpm build` - Build for production
13- `pnpm preview` - Build and preview with Wrangler (Cloudflare Workers)
14- `pnpm check` - Run svelte-check for type checking
15- `pnpm lint` - Run Prettier check and ESLint
16- `pnpm format` - Format code with Prettier
17- `pnpm deploy` - Build and deploy to Cloudflare Workers
18
19## Code Quality Requirements
20
21Before submitting changes:
22
231. **Run `pnpm check`** - Must complete with 0 errors and 0 warnings
242. **Run `pnpm format`** - Format all code with Prettier
25
26## Architecture
27
28### Tech Stack
29
30- **Framework**: SvelteKit 2 with Svelte 5 (using runes: `$state`, `$derived`, `$props`)
31- **Styling**: Tailwind CSS 4 with container queries (`@container`)
32- **Deployment**: Cloudflare Workers via `@sveltejs/adapter-cloudflare`
33- **UI Components**: `@foxui/core`, `@foxui/social` (custom component libraries)
34
35### Grid System
36
37The site uses an 8-column grid layout (`COLUMNS = 8` in `src/lib/index.ts`). Each card has:
38
39- Desktop position/size: `x`, `y`, `w`, `h`
40- Mobile position/size: `mobileX`, `mobileY`, `mobileW`, `mobileH`
41
42Grid margins: 16px desktop, 12px mobile.
43
44### Key Components
45
46**Website Rendering:**
47
48- `src/lib/website/Website.svelte` - Read-only view of a user's bento grid
49- `src/lib/website/EditableWebsite.svelte` - Full editing interface with drag-and-drop, card creation, and save functionality
50- `src/lib/website/Settings.svelte` and `src/lib/website/Profile.svelte` - Editing panels and profile UI
51- Styling: two colors: base color (one the gray-ish tailwind colors: `gray`, `neutral`, `stone`, ...) and accent color (one of the not-gray-ish tailwind color: `rose`, `red`, `amber`, ...)
52
53**Card System (`src/lib/cards/`):**
54
55- `CardDefinition` type in `types.ts` defines the interface for card types
56- Each card type exports a definition with: `type`, `contentComponent`, optional `editingContentComponent`, `creationModalComponent`, `sidebarButtonText`, `loadData`, `upload` (see more info and description in `src/lib/cards/types.ts`)
57- Card types include Text, Link, Image, Bluesky, Embed, Map, Livestream, ATProto collections, and special cards (see `src/lib/cards`).
58- `AllCardDefinitions` and `CardDefinitionsByType` in `index.ts` aggregate all card types
59- See e.g. `src/lib/cards/EmbedCard/` and `src/lib/cards/LivestreamCard/` for examples of implementation.
60- Cards should be styled to work in light and dark mode (with `dark:` class modifier) as well as when cards are colorful (= bg-color-500 for the card background) (with `accent:` modifier).
61
62**ATProto Integration (`src/lib/oauth/`):**
63
64- `auth.svelte.ts` - OAuth client state and login/logout flow using `@atcute/oauth-browser-client`
65- `atproto.ts` - ATProto API helpers: `resolveHandle`, `listRecords`, `getRecord`, `putRecord`, `deleteRecord`, `uploadImage`
66- Data is stored in user's PDS under collection `app.blento.card`
67- **Important**: ATProto does not allow floating point numbers in records. All numeric values must be integers.
68
69**Data Loading (`src/lib/website/`):**
70
71- `load.ts` - Fetches user data from their PDS, with optional KV caching via `UserCache`
72- `data.ts` - Defines which collections/records to fetch
73- `context.ts` - Svelte contexts for passing DID, handle, and data down the component tree
74
75### Routes
76
77- `/` - Landing page
78- `/[handle]/[[page]]` - View a user's bento site (loads from their PDS)
79- `/[handle]/[[page]]/edit` - Edit mode for a user's site page
80- `/edit` - Self-hosted edit mode
81- `/api/links` - Link preview API
82- `/api/geocoding` - Geocoding API for map cards
83- `/api/instagram`, `/api/reloadRecent`, `/api/update` - Additional data endpoints
84
85### Item Type
86
87Cards are represented by the `Item` type (`src/lib/types.ts`) with grid position, size, cardType, and cardData properties.
88
89### Collision/Layout Helpers
90
91`src/lib/helper.ts` contains grid layout algorithms:
92
93- `fixAllCollisions` - Push cards down when they overlap
94- `compactItems` - Move cards up to fill gaps
95- `simulateFinalPosition` - Preview where a dragged card will land