How common-ground-dao/cgsampleplugin works
Project type and purpose
• This is a “plugin” project built with Next.js (App Router) and TypeScript. It serves as a reference implementation for the Common Ground Plugin Library (CGPluginLib).
• It has both frontend UI components (React/Next.js pages) and backend API routes (Next.js serverless functions) but no standalone database—persistent data comes from the external Common Ground platform.
File structure
• Top-level files:
• .env/.env.sample – environment variables for API keys or secrets
• next.config.ts, tsconfig.json – Next.js & TypeScript configuration
• postcss.config.mjs, tailwind.config.ts, eslint.config.mjs – styling & linting
• public/ – static assets (images, favicon)
• src/app/ – Next.js App Router:
• layout.tsx – root layout (shared UI shell)
• page.tsx – main plugin UI entry point
• myInfo.tsx – an additional plugin page
• api/sign/route.ts – serverless function to handle “sign” requests
• globals.css – global TailwindCSS styles
• No lib/ or db/ directories—external services supply all data.
README for additional insights
• Describes how the plugin runs inside an iframe in the Common Ground UI.
• Emphasizes frontend↔backend interactions via the CGPluginLib and the Next.js API route.
• Outlines dev setup (ngrok for tunneling, Yarn commands) and deployment strategies (Vercel, Netlify).
Main components
a. Frontend (Next.js App)
• React components under src/app/*.tsx
• Uses CGPluginLib client to fetch data from Common Ground
b. Backend API (Next.js serverless routes)
• src/app/api/sign/route.ts handles signing requests (e.g. transactions, auth)
• Reads environment variables (.env) for secrets/keys
c. External Service (Common Ground Platform)
• Hosts the plugin in an iframe
• Serves plugin data and expects plugin callbacks (e.g. signing)
d. Hosting/Infrastructure
• Vercel/Netlify (or local ngrok) serving the Next.js app
• CI/CD pipeline (optional) to automatically deploy on push
Relationships and interactions
• User → Browser: loads the Common Ground interface
• Common Ground UI → iFrame: embeds the plugin’s public URL
• iFrame (Plugin Frontend) ↔ CGPluginLib: fetches user/context data from Common Ground via postMessage or REST
• Plugin Frontend → Plugin Backend (Next.js API): HTTP calls to /api/sign to perform secure operations
• Plugin Backend → Common Ground API (external): forwards or signs requests, using secrets from .env
• Hosting (Vercel/ngrok) serves both frontend and API as a unified Next.js application
Architectural patterns and design principles
• Separation of concerns:
• UI layer (.tsx pages)
• Serverless API layer (route.ts)
• App Router (Next.js 13+) for file-based routing
• Environment-driven configuration for secrets
• CSS-infrastructure via Tailwind and PostCSS
• Extensible plugin pattern via CGPluginLib integration