Module Deep Dives

Understanding Our React Marketplace's Architecture

This section provides comprehensive deep dives into each type of module in our React marketplace.

Remember: This is our marketplace's organizational structure. Your marketplace can organize modules differently (Level 1 Personalization).

🎯 What You'll Learn

Each deep-dive page explains:

• What the module type is
• Why we need it
• When to use it
• How it works
• Real examples from our marketplace

📚 Available Deep Dives

Adapters Deep Dive →

Universal SDK Configuration (Framework-Agnostic)

Learn about:

• What adapters are and why they exist
• Framework-agnostic principle
• When to create an adapter
• Real examples: Better Auth, Stripe, Vercel AI SDK
• How connectors import from adapters

Key Concept: Adapters configure SDKs universally, without framework coupling.

Connectors Deep Dive →

SDK + Framework Integration

Learn about:

• What connectors are and why they exist
• The Adapter → Connector pattern
• When to create a connector
• Backend Overwrites Hooks pattern (priority system)
• Real examples: better-auth-nextjs, stripe-nextjs-drizzle
• Category-first organization

Key Concept: "A connector cannot exist without the adapters it tries to connect."

Features Deep Dive →

Complete Business Capabilities

Learn about:

• Backend / Tech-Stack / Frontend structure
• When backend is needed (decision tree!)
• All integration patterns (SDK, API, Custom)
• Tech-Stack as the contract layer
• Real examples: Auth, Payments, Teams
• Backend Overwrites Hooks pattern

Key Concept: Features use 3 layers with tech-stack as single source of truth.

🔄 How They Work Together

The Flow:

1. Adapter (Universal)

adapters/auth/better-auth/
├── config.ts          (Universal Better Auth config)
├── client.ts          (Auth client)
└── types.ts           (Core auth types)

→ Deployed to: src/lib/auth/
→ Framework-agnostic: Works with Next.js, Remix, etc.

2. Connector (Framework-Specific)

connectors/auth/better-auth-nextjs/
├── config.ts          (Imports adapter, adds Next.js plugins)
├── api/route.ts       (Next.js API routes)
├── middleware.ts      (Next.js middleware)
└── hooks.ts           (SDK-native hooks, priority 2)

→ Requires: adapters/auth/better-auth
→ Provides: Next.js-specific integration

3. Feature (Business Logic)

features/auth/
├── tech-stack/        (Schemas, types, generic hooks, UI stores)
└── frontend/shadcn/   (UI components)

❌ No backend/ needed (connector handles it!)

📋 Quick Reference

🎯 Common Questions

Q: When do I create an adapter vs connector?

Adapter:

• ✅ Configuring a new SDK/library
• ✅ Want framework-agnostic setup
• ✅ Can be reused across frameworks
• Example: adapters/auth/better-auth/

Connector:

• ✅ Integrating SDK with specific framework
• ✅ Need framework-specific code (API routes, middleware)
• ✅ Want to provide SDK-native hooks
• Example: connectors/auth/better-auth-nextjs/

Q: When do I need a backend in my feature?

Backend NOT needed (❌):

• SDK + connector handle everything
• Example: Auth with Better Auth

Backend OPTIONAL (⚠️):

• External API provides core functionality
• Only need custom business logic
• Example: Payments with Stripe

Backend REQUIRED (✅):

• No SDK available
• Custom business logic needed
• Example: Teams Management

→ See Features Deep Dive for decision tree!

Q: What's the Backend Overwrites Hooks pattern?

Tech-stack provides generic hooks (priority 1):

// features/auth/tech-stack/hooks.ts
export function useSession() {
  return useQuery({ /* generic fetch */ });
}

Connector provides SDK-native hooks (priority 2 - WINS!):

// connectors/auth/better-auth-nextjs/hooks.ts
export { useSession } from '@/lib/auth/client';  // Better Auth native

→ Frontend imports from @/lib/auth and gets the best version available!

→ See Connectors Deep Dive for details!

🚀 Where to Start?

I want to understand adapters

→ Adapters Deep Dive

I want to understand connectors

→ Connectors Deep Dive

I want to understand features

→ Features Deep Dive

I want the big picture

→ Architecture & Concepts

💡 Why Deep Dives Matter

Problem: Main architecture page was getting too long and verbose.

Solution: Dedicated deep-dive pages for each module type.

Benefit:

• ✅ Main architecture page stays concise
• ✅ Users can choose their depth
• ✅ All patterns explained with real examples
• ✅ No redundancy or conflicts

🎓 Learning Path

Quick Overview (15 minutes):

1. Read Architecture & Concepts Parts 1-3
2. Understand the big picture
3. Done!

Deep Understanding (1-2 hours):

1. Read Architecture & Concepts
2. Deep dive into Adapters
3. Deep dive into Connectors
4. Deep dive into Features
5. Understand all patterns and examples
6. Done!

You choose your depth! ✅

📚 Next Steps

• Adapters Deep Dive → - Universal SDK configuration
• Connectors Deep Dive → - Framework integration
• Features Deep Dive → - Business capabilities
• Architecture Overview → - High-level concepts
• Contributing → - Build your own modules

Choose a deep dive above to get started! 🚀