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...

• 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

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

Metacord uses main as its target integration line and short-lived branches attached to one bounded Loaf Change. The existing dev branch is transitional and must be reconciled before it is retired.

• Vision — product purpose, users, success, and non-goals
• Strategy — current focus, constraints, and open questions
• Architecture — technology-neutral system boundaries and principles
• Decisions — concrete implementation decisions
• Deployment — environment and deployment guidance

docs/PRD.md is retained as a historical requirements snapshot; the operating documents above are current authority.

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

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:8787/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 local secrets for Wrangler:

   cp .dev.vars.development.example .dev.vars.development
   # Edit .dev.vars.development with your Discord credentials, SESSION_SECRET, and DEV_ASSETS_URL

5. Start development:

   pnpm dev

Local development runs Vite on http://localhost:5173 and Wrangler on http://localhost:8787. Wrangler v4 no longer supports --proxy, so the worker proxies non-API requests to the Vite dev server when DEV_ASSETS_URL is set (defaulted in .dev.vars.development.example) while keeping HMR active.

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.

Run the complete local evidence sequence before proposing a Change for landing:

pnpm install --frozen-lockfile
pnpm types
pnpm exec tsc --noEmit
pnpm exec tsc --noEmit -p tsconfig.backend.json
pnpm build
pnpm test

Local checks do not prove a deployment. Record development and production smoke results separately without committing credentials or personal Discord data.

See docs/deployment.md.

metacord/
├── src/
│   ├── index.html          # SPA entry point
│   ├── main.ts             # Application logic
│   ├── worker.ts           # Cloudflare Worker entry (assets + API)
│   ├── 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/
│   ├── VISION.md           # Product purpose and boundaries
│   ├── STRATEGY.md         # Current focus and open questions
│   ├── ARCHITECTURE.md     # Durable logical system model
│   ├── decisions/          # Concrete implementation decisions
│   └── PRD.md              # Historical requirements snapshot
├── vite.config.ts          # Vite build config
├── wrangler.toml           # Cloudflare config
├── tsconfig.json           # TypeScript config
└── .dev.vars.development.example # Local Wrangler dev secrets template

Private - Personal use only