jauntywk.bsky.social
forked from
margin.at/margin
Write on the margins of the internet. Powered by the AT Protocol.
update readme
scanash.com
+44
-35
+44
-35
README.md
+44
-35
README.md
···
2
2
3
3
_Write in the margins of the web_
4
4
5
-
A web comments layer built on [AT Protocol](https://atproto.com) that lets you annotate any URL on the internet.
5
+
A web annotation layer built on [AT Protocol](https://atproto.com) that lets you annotate, highlight, and bookmark any URL on the internet.
6
6
7
7
## Project Structure
8
8
···
13
13
│ ├── annotation.json
14
14
│ ├── bookmark.json
15
15
│ ├── collection.json
16
-
│ └── collectionItem.json
17
-
│ └── highlight.json
18
-
│ └── like.json
19
-
│ └── reply.json
16
+
│ ├── collectionItem.json
17
+
│ ├── highlight.json
18
+
│ ├── like.json
19
+
│ ├── reply.json
20
+
│ ├── apikey.json
21
+
│ ├── preferences.json
22
+
│ └── profile.json
20
23
├── backend/ # Go API server
21
24
│ ├── cmd/server/
22
25
│ └── internal/
23
-
├── web/ # React web app
26
+
├── web/ # Astro SSR + React web app
24
27
│ └── src/
25
-
└── extension/ # Browser extension
26
-
├── popup/
27
-
├── content/
28
-
└── background/
28
+
├── extension/ # Browser extension (WXT)
29
+
│ └── src/
30
+
└── avatar/ # Cloudflare Worker for avatar proxying
29
31
```
30
32
31
33
## Getting Started
32
34
33
-
### Backend
35
+
### Docker (Recommended)
36
+
37
+
Run the full stack with Docker:
34
38
35
39
```bash
36
-
cd backend
37
-
go mod tidy
38
-
go run ./cmd/server
40
+
docker compose up -d --build
39
41
```
40
42
41
-
Server runs on http://localhost:8080
43
+
This builds both the Go backend and the Astro frontend into a single container. The Astro SSR server handles all frontend routing, static assets, and OG image generation, while the Go backend serves the API internally.
42
44
43
-
### Docker (Recommended)
45
+
### Development
44
46
45
-
Run the full stack (Backend + Postgres) with Docker:
47
+
#### Backend
46
48
47
49
```bash
48
-
docker compose up -d --build
50
+
cd backend
51
+
go mod tidy
52
+
go run ./cmd/server
49
53
```
50
54
51
-
### Web App
55
+
API server runs on http://localhost:8081
56
+
57
+
#### Web App
52
58
53
59
```bash
54
60
cd web
···
56
62
npm run dev
57
63
```
58
64
59
-
App runs on http://localhost:3000
65
+
Dev server runs on http://localhost:4321 and proxies API requests to the backend.
60
66
61
-
### Browser Extension
67
+
#### Browser Extension
62
68
63
-
#### Chrome
69
+
Built with [WXT](https://wxt.dev):
64
70
65
-
1. Open Chrome → `chrome://extensions`
66
-
2. Enable "Developer mode"
67
-
3. Click "Load unpacked"
68
-
4. Select the `extension/` folder
71
+
```bash
72
+
cd extension
73
+
npm install
74
+
npm run dev # Chrome dev mode
75
+
npm run dev:firefox # Firefox dev mode
76
+
```
77
+
78
+
## Architecture
69
79
70
-
#### Firefox
80
+
In production, a single Docker container runs both services:
71
81
72
-
1. Open Firefox → `about:debugging`
73
-
2. Click "This Firefox"
74
-
3. Click "Load Temporary Add-on"
75
-
4. Select the `manifest.firefox.json` file in the `extension/` folder
82
+
- **Astro SSR** (port 8080, public) — serves the web app, handles SSR for OG meta tags, generates dynamic OG images via satori, and proxies API/auth requests to the backend.
83
+
- **Go API** (port 8081, internal) — handles all API endpoints, OAuth, firehose ingestion, and data storage.
76
84
77
85
## Domain
78
86
79
-
**Domain**: `margin.at`
87
+
**Domain**: `margin.at`
80
88
**Lexicon Namespace**: `at.margin.*`
81
89
82
90
## Tech Stack
83
91
84
-
- **Backend**: Go + Chi + SQLite / PostgreSQL
85
-
- **Frontend**: React 18 + Vite
86
-
- **Extension**: Manifest v3
92
+
- **Backend**: Go + Chi + SQLite
93
+
- **Frontend**: Astro 5 (SSR) + React 19 + Tailwind CSS
94
+
- **OG Images**: satori + @resvg/resvg-js
95
+
- **Extension**: WXT + React + Tailwind CSS
87
96
- **Protocol**: AT Protocol (Bluesky)
88
97
89
98
## License