# common-ground-dao/cgsampleplugin architecture

> Architecture diagram of the GitHub repository common-ground-dao/cgsampleplugin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/common-ground-dao/cgsampleplugin
- Repository: https://github.com/common-ground-dao/cgsampleplugin

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    UserBrowser["User Browser"]:::external
    CommonGroundUI["Common Ground Host UI"]:::external
    IframePlugin["iframe: Plugin URL"]:::external

    %% Plugin Application
    subgraph "Next.js Plugin App"
        direction TB
        subgraph "Frontend (React Pages)" 
            direction TB
            Layout["layout.tsx"]:::frontend
            Page["page.tsx"]:::frontend
            MyInfo["myInfo.tsx"]:::frontend
            Globals["globals.css"]:::frontend
            CGPluginLib["CGPluginLib Client"]:::frontend
        end
        subgraph "Backend (API Routes)"
            direction TB
            SignRoute["route.ts (POST /api/sign)"]:::backend
            Env[".env / .env.sample"]:::backend
        end
    end

    %% External Services
    CommonGroundAPI["Common Ground API"]:::external

    %% Infrastructure
    Hosting["Hosting (Vercel / ngrok)"]:::infra

    %% Connections
    UserBrowser -->|"loads UI"| CommonGroundUI
    CommonGroundUI -->|"embeds iframe"| IframePlugin
    IframePlugin -->|"renders"| Layout
    Layout --> Page
    Layout --> MyInfo
    Page -->|"CGPluginLib fetch"| CGPluginLib
    MyInfo -->|"CGPluginLib fetch"| CGPluginLib
    CGPluginLib -->|"data request"| SignRoute
    SignRoute -->|"uses secrets"| Env
    SignRoute -->|"forwards/signs"| CommonGroundAPI
    Hosting -->|"serves app"| IframePlugin

    %% Click Events
    click Layout "https://github.com/common-ground-dao/cgsampleplugin/blob/main/src/app/layout.tsx"
    click Page "https://github.com/common-ground-dao/cgsampleplugin/blob/main/src/app/page.tsx"
    click MyInfo "https://github.com/common-ground-dao/cgsampleplugin/blob/main/src/app/myInfo.tsx"
    click Globals "https://github.com/common-ground-dao/cgsampleplugin/blob/main/src/app/globals.css"
    click SignRoute "https://github.com/common-ground-dao/cgsampleplugin/blob/main/src/app/api/sign/route.ts"
    click Env "https://github.com/common-ground-dao/cgsampleplugin/blob/main/.env"
    click Env "https://github.com/common-ground-dao/cgsampleplugin/blob/main/.env.sample"
    click NextConfig "https://github.com/common-ground-dao/cgsampleplugin/blob/main/next.config.ts"
    click Tsconfig "https://github.com/common-ground-dao/cgsampleplugin/blob/main/tsconfig.json"
    click Tailwind "https://github.com/common-ground-dao/cgsampleplugin/blob/main/tailwind.config.ts"
    click Postcss "https://github.com/common-ground-dao/cgsampleplugin/blob/main/postcss.config.mjs"
    click Eslint "https://github.com/common-ground-dao/cgsampleplugin/blob/main/eslint.config.mjs"
    click Public "https://github.com/common-ground-dao/cgsampleplugin/tree/main/public/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef external fill:#D0F5D0,stroke:#28a745,color:#28a745
    classDef infra fill:#F0F0F0,stroke:#6a737d,color:#6a737d
```
