How flotob/cgsampleplugin works
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)