Margin

Write in the margins of the web

A web annotation layer built on AT Protocol that lets you annotate, highlight, and bookmark any URL on the internet.

Project Structure

margin/
├── lexicons/           # AT Protocol lexicon schemas
│   └── at/margin/
│       ├── annotation.json
│       ├── bookmark.json
│       ├── collection.json
│       ├── collectionItem.json
│       ├── highlight.json
│       ├── like.json
│       ├── reply.json
│       ├── apikey.json
│       ├── preferences.json
│       └── profile.json
├── backend/            # Go API server
│   ├── cmd/server/
│   └── internal/
├── web/                # Astro SSR + React web app
│   └── src/
├── extension/          # Browser extension (WXT)
│   └── src/
└── avatar/             # Cloudflare Worker for avatar proxying

Getting Started

Docker (Recommended)

Run the full stack with Docker:

docker compose up -d --build

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.

Development

Backend

cd backend
go mod tidy
go run ./cmd/server

API server runs on http://localhost:8081

Web App

cd web
bun install
bun run dev

Dev server runs on http://localhost:4321 and proxies API requests to the backend.

Browser Extension

Built with WXT:

cd extension
bun install
bun run dev          # Chrome dev mode
bun run dev:firefox  # Firefox dev mode

Architecture

In production, a single Docker container runs both services:

• 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.
• Go API (port 8081, internal) — handles all API endpoints, OAuth, firehose ingestion, and data storage.

Domain

Domain: margin.at
Lexicon Namespace: at.margin.*

Tech Stack

• Backend: Go + Chi + SQLite
• Frontend: Astro 5 (SSR) + React 19 + Tailwind CSS
• OG Images: satori + @resvg/resvg-js
• Extension: WXT + React + Tailwind CSS
• Protocol: AT Protocol (Bluesky)

Sponsors

Thank you for making Margin possible!

Infrastructure Sponsor

Bryan
@chaosgreml.in

GitHub Sponsors

Translations

Help translate Margin at translate.margin.at.

License

MIT