Skip to content

akshzyx/fedpin

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

18 Commits
cmd/server
cmd/server
 
 
internal
internal
 
 
scripts
scripts
 
 
.air.toml
.air.toml
 
 
.gitignore
.gitignore
 
 
Makefile
Makefile
 
 
README.md
README.md
 
 
docker-compose.dev.yml
docker-compose.dev.yml
 
 
go.mod
go.mod
 
 
go.sum
go.sum
 
 

Repository files navigation

FedPin

A federated Pinterest-style application built on ActivityPub. Users can create pins, organize boards, follow each other, and interact across the Fediverse with Mastodon, Pixelfed, and other compatible platforms.

Tech Stack

Backend

  • Go 1.25+
  • Fiber v3
  • PostgreSQL 17
  • Bun ORM
  • Redis
  • MinIO / S3
  • ActivityPub (planned)
  • Asynq (planned)

Frontend (planned)

  • Nuxt 4 (SPA mode)
  • TypeScript
  • Tailwind CSS
  • Pinia
  • Nuxt UI v3

Infrastructure

  • Docker Compose (local dev)
  • golang-migrate
  • Air (hot reload)
  • Resend (email)

Features

Done

  • Auth — signup, login, refresh tokens, logout, JWT, email verification, password change, email change with verification
  • Roles — owner, admin, moderator, user (first registered user becomes owner)
  • Pins — upload images, title, description, alt text, tags, privacy, blurhash, thumbnails, download tracking
  • Boards — create boards, add/remove pins, reorder, cover image, privacy
  • Social — follow/unfollow, like/unlike, comments, repins, downloads
  • Feed — home feed, explore feed, trending, user feed, cursor-based infinite scroll, Redis caching
  • Notifications — follow, like, comment, repin notifications with unread count
  • Storage — MinIO image upload, original + thumbnail, automatic cleanup on delete
  • Privacy — private pins, boards, and accounts hidden from non-followers
  • User profiles — update display name, bio, website, location, avatar, privacy setting
  • Block system — block/unblock users, removes follows in both directions
  • Saved pins — save/unsave pins, enriched response with pin and author data
  • Pin tags — up to 8 tags per pin, normalized and deduplicated
  • Related pins — tag overlap, same user, trending fallback tiers
  • Suggested users — excludes followed, followers, blocked, and private accounts
  • Instance settings — owner can configure name, description, rules, registration, upload limits
  • Search — search pins, users, and boards with ILIKE matching
  • Reports — report pins, comments, boards, and users with reason
  • Admin panel — ban, warn, promote, delete content, manage permissions
  • Moderation logs — full audit trail of all admin and moderator actions
  • Permission system — per-user toggles for upload, comment, like, follow, report
  • Role-based access — owner, admin, moderator with distinct capabilities enforced at route level

Planned

  • Comment replies
  • Federation (ActivityPub)
  • WebSocket real-time notifications
  • PWA push notifications
  • Nuxt 4 frontend

Project Structure

fedpin/
├── cmd/server/          # entrypoint
├── internal/
│   ├── app/             # bootstrap, http server, shutdown
│   ├── config/          # env config loading
│   ├── database/        # postgres + redis connections
│   ├── domain/
│   │   ├── auth/        # JWT, signup, login, email verify, password/email change
│   │   ├── user/        # user model, profile update, suggestions
│   │   ├── pin/         # pin upload, CRUD, tags, related pins
│   │   ├── board/       # boards, board pins, reorder
│   │   ├── follow/      # follow/unfollow with feed cache invalidation
│   │   ├── like/        # like/unlike
│   │   ├── comment/     # comments
│   │   ├── repin/       # repins
│   │   ├── feed/        # home, explore, trending, user feeds
│   │   ├── notification/# notifications, unread count
│   │   ├── block/       # block/unblock users
│   │   ├── saved/       # save/unsave pins
│   │   ├── instance/    # instance settings
│   │   ├── search/      # search pins, users, boards
│   │   ├── report/      # content and user reports
│   │   └── admin/       # admin panel, moderation, logs
│   ├── mail/            # Resend email client + templates
│   ├── middleware/      # Auth, OptionalAuth, RequireRole
│   └── storage/         # MinIO upload, delete, thumbnail
├── pkg/                 # shared packages (activitypub planned)
├── scripts/             # migrate.sh
├── frontend/            # Nuxt 4 (planned)
└── deployments/         # Docker, CI/CD (planned)

API Routes

Auth

POST   /api/v1/auth/signup
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh
POST   /api/v1/auth/logout
GET    /api/v1/auth/verify-email?token=
GET    /api/v1/auth/confirm-email-change?token=
POST   /api/v1/auth/resend-verification        (auth)
POST   /api/v1/auth/change-password            (auth)
POST   /api/v1/auth/change-email               (auth)
GET    /api/v1/me                              (auth)

Users

GET    /api/v1/users/:username
GET    /api/v1/users/suggestions               (auth)
GET    /api/v1/users/me/saved                  (auth)
GET    /api/v1/users/me/blocked                (auth)
GET    /api/v1/users/:id/followers
GET    /api/v1/users/:id/following
PATCH  /api/v1/users/me/profile                (auth)
POST   /api/v1/users/:id/follow                (auth)
DELETE /api/v1/users/:id/follow                (auth)
POST   /api/v1/users/:id/block                 (auth)
DELETE /api/v1/users/:id/block                 (auth)

Pins

GET    /api/v1/pins/user/:userID
GET    /api/v1/pins/:id
GET    /api/v1/pins/:id/download
GET    /api/v1/pins/:id/related
GET    /api/v1/pins/:id/comments
POST   /api/v1/pins                            (auth)
PATCH  /api/v1/pins/:id                        (auth)
DELETE /api/v1/pins/:id                        (auth)
POST   /api/v1/pins/:id/like                   (auth)
DELETE /api/v1/pins/:id/like                   (auth)
POST   /api/v1/pins/:id/save                   (auth)
DELETE /api/v1/pins/:id/save                   (auth)
POST   /api/v1/pins/:id/repin                  (auth)
DELETE /api/v1/pins/:id/repin                  (auth)
POST   /api/v1/pins/:id/comments               (auth)
DELETE /api/v1/comments/:id                    (auth)

Boards

GET    /api/v1/boards/user/:userID
GET    /api/v1/boards/:id
GET    /api/v1/boards/:id/pins
POST   /api/v1/boards                          (auth)
PATCH  /api/v1/boards/:id                      (auth)
DELETE /api/v1/boards/:id                      (auth)
POST   /api/v1/boards/:id/pins                 (auth)
DELETE /api/v1/boards/:id/pins/:pinID          (auth)
PATCH  /api/v1/boards/:id/reorder              (auth)

Feed

GET    /api/v1/feed/home                       (auth)
GET    /api/v1/feed/explore
GET    /api/v1/feed/trending
GET    /api/v1/feed/user/:userID

Notifications

GET    /api/v1/notifications                   (auth)
POST   /api/v1/notifications/read-all          (auth)
PATCH  /api/v1/notifications/:id/read          (auth)

Search

GET    /api/v1/search?q=&type=pins|users|boards|all

Reports

POST   /api/v1/reports                         (auth)
GET    /api/v1/admin/reports                   (mod+)
POST   /api/v1/admin/reports/:id/resolve       (mod+)

Instance

GET    /api/v1/instance
GET    /api/v1/admin/instance                  (owner)
PATCH  /api/v1/admin/instance                  (owner)

Admin

GET    /api/v1/admin/stats                     (admin+)
GET    /api/v1/admin/logs                      (admin+)
GET    /api/v1/admin/users                     (admin+)
GET    /api/v1/admin/users/:id                 (admin+)
POST   /api/v1/admin/users/:id/ban             (admin+)
POST   /api/v1/admin/users/:id/unban           (admin+)
POST   /api/v1/admin/users/:id/warn            (mod+)
POST   /api/v1/admin/users/:id/promote         (admin+)
PATCH  /api/v1/admin/users/:id/note            (mod+)
PATCH  /api/v1/admin/users/:id/permissions     (admin+)
DELETE /api/v1/admin/pins/:id                  (mod+)
DELETE /api/v1/admin/comments/:id              (mod+)
DELETE /api/v1/admin/boards/:id                (mod+)

Role Capabilities

Action Moderator Admin Owner
Warn users Yes Yes Yes
Delete content Yes Yes Yes
Update admin notes Yes Yes Yes
View reports Yes Yes Yes
Ban/unban users No Yes Yes
Update permissions No Yes Yes
Promote to moderator No Yes Yes
Promote to admin No No Yes
Manage instance No No Yes

Getting Started

Prerequisites

  • Go 1.25+
  • Docker + Docker Compose
  • golang-migrate CLI
  • air for hot reload

Install tools

go install github.com/air-verse/air@latest
go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

Setup

# clone repo
git clone https://github.com/akshzyx/fedpin
cd fedpin

# copy env
cp .env.example .env

# start postgres + redis + minio
make up

# run migrations
make migrate-up

# start backend
make air

Environment Variables

APP_ENV=development
APP_HOST=0.0.0.0
APP_PORT=8888
MAX_UPLOAD_SIZE_MB=5

POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=fedpin
POSTGRES_PASSWORD=fedpin
POSTGRES_DB=fedpin

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=fedpin
MINIO_SECRET_KEY=fedpin123
MINIO_BUCKET=fedpin
MINIO_USE_SSL=false

JWT_SECRET=change-me-in-production
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=168h

RESEND_API_KEY=re_xxxxxxxxxxxx
RESEND_FROM=noreply@yourdomain.com
APP_URL=http://localhost:8888

Makefile Commands

make dev                           # start services + migrate + air
make up                            # start docker services
make down                          # stop docker services
make air                           # run backend with hot reload
make migrate-up                    # run all migrations
make migrate-down                  # rollback last migration
make migrate-create name=table     # new migration
make reset-db                      # drop all + rerun migrations

Database Schema

Table Description
users accounts, roles, permissions
refresh_tokens JWT refresh tokens
pins image pins with metadata and tags
boards pin collections
board_pins pin to board join with position
follows user follow relationships
likes pin likes
comments pin comments
repins pin repins to boards
notifications activity notifications
blocks user block relationships
saved_pins bookmarked pins per user
instance_settings instance configuration
reports content and user reports
moderation_logs audit trail of admin actions

Federation (Planned)

FedPin will implement ActivityPub for Fediverse compatibility.

FedPin ActivityPub
Pin Image
Board Collection
Repin Announce
Comment Note
Like Like
Follow Follow

Users will be addressable as username@instance.com via WebFinger.

Roadmap

Feature Status
Project bootstrap Done
Database and migrations Done
Auth and users Done
Pins and storage Done
Boards Done
Social interactions Done
Feed system Done
Notifications and email Done
User features and settings Done
Search, admin, moderation Done
Federation (ActivityPub) Planned
Jobs, WebSocket, PWA Planned
Nuxt 4 frontend Planned
Production and CI/CD Planned

License

MIT

About

A Pinterest-style application for creating and organizing pins, built on ActivityPub to enable interaction across the Fediverse.

Topics

social-network decentralized image-sharing activitypub fediverse

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages