# flotob/cgsampleplugin architecture

> Architecture diagram of the GitHub repository flotob/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/flotob/cgsampleplugin
- Repository: https://github.com/flotob/cgsampleplugin

## Overview

##### Project Type and Purpose
- This is a full-stack Next.js plugin (“OnBoard: Common Ground Wizard Plugin”) designed to be embedded in the Common Ground platform.
- It provides both an Admin UI for creating/configuring multi-step “wizards” and a User UI for end-users to progress through those wizards.
- Core purpose: guide users through credential verification (ENS), content slides, quizzes, and potentially earn roles; all backed by a PostgreSQL database and integrated with external services (Stripe, OpenAI, Ethereum/ENS).

##### High-Level Architectural Components
a. Frontend (Browser)
- Next.js App Router pages under src/app
- React components (src/components)
- State & data layer: React Query hooks (src/hooks), Context Providers (AuthContext, CgLibContext)
- UI styling: Tailwind CSS & shadcn/ui components
- Hosted inside an iframe in the Common Ground host
b. Backend (Plugin Server)
- Next.js API Routes under src/app/api
- Authentication middleware: withAuth HOC (src/lib/withAuth.ts) for JWT verification & profile upsert
- Business logic & services: wizardAdminService, quotas, onboardingDbService, storage, step-logic (src/lib)
- Database migrations: node-pg-migrate files in migrations/
c. Database
- PostgreSQL (tables: onboarding_wizards, onboarding_steps, step_types, user_profiles, user_wizard_sessions, user_wizard_progress, user_wizard_completions, generated_images, quotas, etc.)
- Managed via Docker Compose locally (docker-compose.yml)
d. External Services
- Stripe (Checkout, Portal sessions, Webhooks – /api/stripe, /api/webhooks/stripe)
- OpenAI (DALL·E 3 for background generation – /api/admin/steps/generate-background)
- Object Storage (S3-compatible via src/lib/storage.ts)
- Ethereum/ENS via wagmi & ethereum-identity-kit for ENS verification

##### Interactions and Data Flow
- User (admin or end-user) loads the plugin in their browser → React app initializes (uses cg-plugin-lib to obtain community/context) → POST /api/auth/session → JWT returned
- Frontend attaches JWT to subsequent API calls via authFetch → withAuth validates JWT and injects req.user → handlers perform business logic and interact with the database via db.ts queries
- Admin flows: CRUD wizards & steps, reorder steps, generate AI images (call OpenAI → store images → save metadata)
- User flows: launch wizard → WizardSlideshowModal fetches user session and progress → display step component → upon completion, call user progress API → record in user_wizard_progress, update user_wizard_sessions → optionally assign role → trigger JWT refresh via useAssignRoleAndRefresh/useMarkWizardCompleted hooks
- Stripe flows: frontend creates checkout/portal sessions → Stripe redirects back to plugin → webhook events update community plan in database → plugin fetches updated quotas

##### Architectural Patterns & Design Principles
- Next.js App Router with React Server/Client components separation
- JWT-based auth with a HOC middleware (withAuth) enforcing admin-only routes
- React Query for data fetching, mutations, polling, and cache invalidation
- Context API for global state (AuthContext, CgLibContext, StripeWaitContext)
- Database migrations for schema evolution
- Modular code organization:
- UI components (admin vs. user vs. shared)
- Hooks for data logic
- lib/services for business rules
- API routes grouped by domain (admin, auth, community, user, onboarding, stripe, webhooks, wizards)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser / Plugin Iframe
    subgraph "Browser / Plugin Iframe" 
        direction TB
        PluginContainer["PluginContainer (Iframe Host Integration)"]:::frontend
        ReactApp["Next.js Frontend (App Router Pages & Layout)"]:::frontend
        SharedUI["Shared UI Components"]:::frontend
        AdminUI["Admin UI Components"]:::frontend
        OnboardingUI["Onboarding Wizard UI"]:::frontend
        StepDisplayUI["Onboarding Step Displays"]:::frontend
        ReactQuery["React Query Hooks"]:::frontend
        AuthContext["AuthContext"]:::frontend
        CgLibContext["CgLibContext"]:::frontend
        StripeWaitContext["StripeWaitContext"]:::frontend
        Styling["Tailwind CSS & shadcn/ui"]:::frontend
    end

    %% Next.js Server / API
    subgraph "Next.js Server (Plugin Server)" 
        direction TB
        APIRoutes["API Routes (/src/app/api)"]:::backend
        AuthMiddleware["withAuth Middleware"]:::backend
        BusinessServices["Business Logic & Services"]:::backend
        DBConnector["DB Connector & Queries (db.ts)"]:::backend
        Migrations["Migrations"]:::backend
    end

    %% Database
    subgraph "PostgreSQL Database" 
        direction TB
        DB["PostgreSQL"]:::database
    end

    %% External Integrations
    subgraph "External Services" 
        direction TB
        Stripe["Stripe Checkout & Billing Portal"]:::external
        StripeWebhook["Stripe Webhook Receiver"]:::external
        OpenAI["OpenAI API (DALL·E)"]:::external
        S3Storage["S3-compatible Storage"]:::external
        Ethereum["Ethereum/ENS RPC"]:::external
    end

    %% Browser to Server
    PluginContainer -->|load plugin| ReactApp
    ReactApp -->|POST /api/auth/session| APIRoutes
    ReactApp -->|GET/POST /api/*| APIRoutes
    ReactQuery --> ReactApp
    AuthContext --> ReactApp
    CgLibContext --> ReactApp
    StripeWaitContext --> ReactApp

    %% Server internals
    APIRoutes -->|uses| AuthMiddleware
    APIRoutes -->|routes| BusinessServices
    BusinessServices -->|queries| DBConnector
    BusinessServices -->|runs| Migrations
    DBConnector -->|connects| DB

    %% Server to External
    BusinessServices -->|create checkout/session| Stripe
    BusinessServices -->|listen webhooks| StripeWebhook
    BusinessServices -->|generate images| OpenAI
    BusinessServices -->|upload/download| S3Storage
    BusinessServices -->|ENS queries| Ethereum

    %% External back to Server
    StripeWebhook -->|POST /api/webhooks/stripe| APIRoutes

    %% Components Click Events
    click ReactApp "https://github.com/flotob/cgsampleplugin/tree/main/src/app"
    click SharedUI "https://github.com/flotob/cgsampleplugin/tree/main/src/components"
    click AdminUI "https://github.com/flotob/cgsampleplugin/tree/main/src/components/admin"
    click OnboardingUI "https://github.com/flotob/cgsampleplugin/tree/main/src/components/onboarding"
    click StepDisplayUI "https://github.com/flotob/cgsampleplugin/tree/main/src/components/onboarding/steps/display"
    click ReactQuery "https://github.com/flotob/cgsampleplugin/tree/main/src/hooks"
    click AuthContext "https://github.com/flotob/cgsampleplugin/blob/main/src/context/AuthContext.tsx"
    click CgLibContext "https://github.com/flotob/cgsampleplugin/blob/main/src/context/CgLibContext.tsx"
    click StripeWaitContext "https://github.com/flotob/cgsampleplugin/blob/main/src/context/StripeWaitContext.tsx"
    click Styling "https://github.com/flotob/cgsampleplugin/blob/main/tailwind.config.ts"
    click PluginContainer "https://github.com/flotob/cgsampleplugin/blob/main/src/app/PluginContainer.tsx"
    click AuthMiddleware "https://github.com/flotob/cgsampleplugin/blob/main/src/lib/withAuth.ts"
    click BusinessServices "https://github.com/flotob/cgsampleplugin/blob/main/src/lib/services/wizardAdminService.ts"
    click BusinessServices "https://github.com/flotob/cgsampleplugin/blob/main/src/lib/quotas.ts"
    click BusinessServices "https://github.com/flotob/cgsampleplugin/blob/main/src/lib/onboardingDbService.ts"
    click BusinessServices "https://github.com/flotob/cgsampleplugin/tree/main/src/lib/step-logic"
    click BusinessServices "https://github.com/flotob/cgsampleplugin/blob/main/src/lib/storage.ts"
    click DBConnector "https://github.com/flotob/cgsampleplugin/blob/main/src/lib/db.ts"
    click Migrations "https://github.com/flotob/cgsampleplugin/tree/main/migrations/"
    click APIRoutes "https://github.com/flotob/cgsampleplugin/tree/main/src/app/api"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#2196F3,color:#0D47A1
    classDef backend fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20
    classDef database fill:#F3E5F5,stroke:#9C27B0,color:#4A148C
    classDef external fill:#FFF3E0,stroke:#FF9800,color:#E65100
```
