Metacord - Your Personal Discord Server Directory

Metacord is a personal Discord server directory, allowing to keep track of current (and previous) servers, adding notes, keeping track of invite links (so you can leave and rejoin later), etc...

Features

• Discord OAuth Login - One-click authentication with PKCE flow
• Server List - View all servers with icons, names, and join dates
• Organization - Favorites, custom nicknames, and personal notes
• Filters - Partner, Verified, Boosted, Discoverable, Owner
• Search - Filter servers by name in real-time
• Export/Import - Backup and restore your user data (JSON)
• Demo Mode - Preview UI without OAuth setup via ?demo=1

Architecture

• Frontend: Static SPA (Vite + TypeScript) on Cloudflare Pages
• Backend: Hono catch-all router in Pages Functions (/api/*)
• Auth: Discord OAuth with PKCE, AES-GCM encrypted tokens in Workers KV
• Storage: KV for sessions, localStorage for user preferences

Development

Prerequisites

• Node.js 18+ with pnpm
• Cloudflare account
• Discord application (discord.com/developers)

Setup

1. Clone and install:

   pnpm install

2. Create Discord application:

   • Go to Discord Developer Portal
   • Create new application, go to OAuth2 settings
   • Add redirect URL: http://localhost:8788/api/auth/callback
   • Copy Client ID and Client Secret

3. Create KV namespace:

   pnpm wrangler kv:namespace create "SESSIONS"
   pnpm wrangler kv:namespace create "SESSIONS" --preview

   Add the IDs to wrangler.toml

4. Configure secrets (requires direnv):

   cp .envrc.example .envrc
   # Edit .envrc with your Discord credentials and SESSION_SECRET
   direnv allow

5. Start development:

   pnpm dev

Tip: Use ?demo=1 to preview the UI without setting up OAuth. Demo mode loads mock data from a guilds_api.json that you can extract from the Console of your browser in a logged in session.

Scripts

Command	Description
pnpm dev	Run Vite + Wrangler concurrently
pnpm build	Build frontend for production
pnpm preview	Preview production build locally

Deployment

See docs/deployment.md.

Project Structure

metacord/
├── src/
│   ├── index.html          # SPA entry point
│   ├── main.ts             # Application logic
│   ├── style.css           # Styles with CSS variables
│   ├── components/         # UI components (modal, serverCard, toast)
│   └── lib/                # Frontend helpers (api, storage, utils)
├── functions/
│   ├── api/
│   │   └── [[route]].ts    # Hono catch-all router
│   └── lib/                # Backend helpers (session, cache, crypto, cookies, http, types)
├── shared/                 # Shared types (placeholder)
├── docs/
│   └── PRD.md              # Product requirements
├── vite.config.ts          # Vite build config
├── wrangler.toml           # Cloudflare config
├── tsconfig.json           # TypeScript config
└── .envrc.example          # Environment template (direnv)

License

Private - Personal use only