Architecture & Core Concepts

Understanding The Architech

This page is your complete guide to understanding The Architech's architecture, from the high-level separation of concerns to the detailed module system.

Part 1: The Big Picture

The Two-Layer Architecture

The Architech is built on a fundamental separation between two independent layers:

┌─────────────────────────────────────┐
│           THE CLI (Engine)          │
│                                     │
│  Generic code generation engine     │
│  Executes blueprints                │
│  No technology opinions             │
└─────────────────────────────────────┘
                  ↓
                  │ Uses blueprints from
                  ↓
┌─────────────────────────────────────┐
│        MARKETPLACE (Fuel)           │
│                                     │
│  Collection of opinionated modules  │
│  Adapters, Connectors, Features    │
│  Technology stack decisions         │
└─────────────────────────────────────┘

The CLI is the engine. The marketplace is the fuel.

Layer 1: The CLI (Unopinionated Engine)

The Architech CLI is a generic, unopinionated code generation engine that can execute any blueprint from any marketplace.

What the CLI provides:

• 🔧 Blueprint execution engine
• 🔧 Virtual File System (VFS) for safety
• 🔧 AST-based file manipulation
• 🔧 Dependency resolution (topological sort)
• 🔧 Type-safe genome system
• 🔧 Error handling & automatic rollback

What the CLI does NOT provide:

• ❌ Technology choices (React vs Vue vs Angular)
• ❌ Architectural patterns
• ❌ Specific modules or templates
• ❌ Opinionated best practices

Deep dive: See CLI Internals → for the complete technical architecture.

Layer 2: Marketplaces (Opinionated Collections)

A Marketplace is a collection of modules that embody specific architectural opinions and technology choices for a particular ecosystem.

What a marketplace provides:

• 🎯 Module blueprints (adapters, connectors, features)
• 🎯 Technology choices and configurations
• 🎯 Architectural patterns and standards
• 🎯 Templates and code snippets
• 🎯 Quality validation and conventions

Examples of marketplaces:

• Our Official React Marketplace (this documentation) - Next.js, TanStack Query, Zustand
• Vue Marketplace (community) - Nuxt, Pinia, VueUse
• Your Company Marketplace (internal) - Your standards, your stack

Why This Separation Matters

Freedom to choose:

• Use our React marketplace if it fits your needs
• Use a Vue, Angular, or Svelte marketplace if you prefer
• Create a company-internal marketplace with your standards
• Switch marketplaces as your needs evolve

No lock-in:

• The CLI is open-source and unopinionated
• Marketplaces are just collections of TypeScript files
• You own all generated code

Want to create your own marketplace? See Creating Your Marketplace →

Part 1.5: Two Levels of Personalization

Understanding What You Can Customize

The Architech offers two independent levels of personalization. This is crucial to understand:

Level 1: Module Structure Personalization

The way we organize modules is OUR choice, not a CLI requirement.

Our React marketplace uses this structure:

marketplace/
├── adapters/      (Universal SDK configurations)
├── connectors/    (Framework integrations)
└── features/      (Business capabilities)

But your marketplace could use:

marketplace/
├── packages/      (Your organization)
├── templates/     (Your organization)
└── presets/       (Your organization)

Or even:

marketplace/
├── ui/            (Your organization)
├── backend/       (Your organization)
└── fullstack/     (Your organization)

The CLI only cares about:

• ✅ Blueprint interface contract
• ✅ Module ID for dependency resolution
• ✅ NOT folder structure or naming conventions

This means: You can organize your marketplace however makes sense for your ecosystem or company. The 3-tier structure (Adapters/Connectors/Features) is our opinionated approach, not a limitation of the platform.

Level 2: Technology Personalization

The technologies we chose are OUR marketplace's decisions, not CLI requirements.

Our React marketplace uses:

{
  framework: 'nextjs',
  stateManagement: 'zustand',
  dataFetching: 'tanstack-query',
  forms: 'react-hook-form + zod',
  testing: 'vitest',
}

A Vue marketplace might use:

{
  framework: 'nuxt',
  stateManagement: 'pinia',
  dataFetching: 'tanstack-query',  // Framework-agnostic!
  forms: 'vee-validate + zod',
  testing: 'vitest',
  ui: 'vuetify' // Yes you can add other opiniated technologies 
}

An Angular marketplace might use:

{
  framework: 'angular',
  stateManagement: 'ngrx',
  dataFetching: 'http-client + rxjs',
  forms: 'angular-reactive-forms',
  testing: 'jest',
  ui: 'angular-material'
}

Your company marketplace might use:

{
  framework: 'your-approved-framework',
  stateManagement: 'your-state-solution',
  dataFetching: 'your-data-layer',
  forms: 'your-form-library',
  testing: 'your-test-framework',
  ui: 'your-design-system'
}

The CLI executes blueprints for ANY technology. It doesn't know (or care) if you're using React, Vue, Angular, Svelte, or something completely custom.

Why This Matters

Freedom:

• ✅ Not locked into our opinions
• ✅ Create marketplaces matching your needs
• ✅ Use familiar tools and patterns
• ✅ Serve different ecosystems

Flexibility:

• ✅ Adapt to different frameworks
• ✅ Support company standards
• ✅ Experiment with new stacks
• ✅ Mix and match as needed

Ownership:

• ✅ Your structure, your rules
• ✅ Your tech, your expertise
• ✅ Your marketplace, your way
• ✅ Your team, your standards

The Path to Your Custom Marketplace

1. Use Our CLI (engine) - It's generic and unopinionated
2. Choose Your Structure (Level 1) - How to organize modules
3. Choose Your Tech (Level 2) - Which libraries and frameworks
4. Create Your Modules - Adapters, connectors, features (or your equivalent)
5. Define Your Standards - Your "Golden Core" (we'll explain this next)

Remember: Everything you see in this documentation about module organization and technology choices is our React marketplace's approach. It's a proven, production-ready pattern — but it's one option, not the only option.

Part 2: Our React Marketplace Philosophy

Important: Everything below describes our official React marketplace's architecture. Other marketplaces can make completely different choices.

Opinionated Core, Agnostic Edges

This is the foundational principle of our marketplace.

The Golden Core (Strong Opinions)

Our React marketplace is unapologetically opinionated about the internal logic of applications. These choices enable powerful abstractions and consistent code quality.

Our marketplace's non-negotiable standards:

1. Data Fetching: TanStack Query

• Why: Industry-leading async state management
• What it gives you: Automatic caching, revalidation, optimistic updates
• Standard API: All generated data hooks follow TanStack Query patterns

2. Client State Management: Zustand

• Why: Minimal boilerplate, maximum power
• What it gives you: Simple, scalable state with zero ceremony
• Standard API: Consistent store patterns across all features

3. Forms & Validation: React Hook Form + Zod

• Why: Type-safe validation with excellent DX
• What it gives you: Schema-based forms with runtime validation
• Standard API: All form hooks use this battle-tested combo

4. Quality & Testing: Vitest + Testing Library + Playwright

• Why: Modern, fast, reliable testing stack
• What it gives you: Unit, integration, and E2E tests that actually work
• Standard API: Consistent testing patterns

Note: An Angular marketplace might use NgRx instead of Zustand. A Vue marketplace might use Pinia. The CLI supports all patterns equally.

The Agnostic Edges (Your Freedom)

We grant total freedom on technologies that interface with the outside world:

UI Libraries

• shadcn/ui, Tamagui, Material-UI, Chakra, custom
• Why agnostic: UI is tied to brand and design systems

Databases & ORMs

• Drizzle, Prisma, Kysely, TypeORM, raw SQL
• Why agnostic: Data persistence varies by scale

Frameworks

• Next.js, Remix, Astro, SvelteKit
• Why agnostic: Different apps need different rendering

Auth Providers

• Better Auth, Clerk, Auth.js, Supabase, custom
• Why agnostic: Auth requirements vary dramatically

Deployment

• Vercel, Docker, AWS, Google Cloud, self-hosted
• Why agnostic: Infrastructure is environment-specific

The Result: Strong opinions where they matter (internal consistency) + flexibility where you need it (external integrations).

Part 2.5: The Golden Core (Consolidated)

Our Marketplace's Foundation

We've consolidated our essential technologies into a single adapter that serves as the foundation for all projects.

The core/golden-stack Adapter

One module. Five technologies. Production-ready.

// In your genome
{
  id: 'core/golden-stack'  // ← Single line includes everything
}

This includes:

1. Zustand (v4.5+) - Client state management

   • UI-only state (modals, filters, preferences)
   • NOT for server data (that's TanStack Query's job)
   • Persistent stores with localStorage/sessionStorage

2. Vitest (v1.0+) - Testing framework

   • Unit tests (fast, isolated)
   • Integration tests (component + logic)
   • Coverage reports
   • Watch mode for development

3. ESLint (v8.0+) - Code linting

   • TypeScript rules
   • React rules (if using React)
   • Accessibility rules
   • Auto-fix on save

4. Prettier (v3.0+) - Code formatting

   • Consistent style across team
   • Integrates with ESLint

5. Zod (v3.22+) - Schema validation

   • Runtime type safety
   • API validation
   • Form validation
   • Database schema validation

Why a Golden Core?

Consistency:

• All features expect these tools
• Patterns are predictable across projects
• Code review becomes systematic
• Onboarding is faster

Composability:

• Features integrate seamlessly
• Hooks work together naturally
• State flows predictably
• Types are consistent

Developer Experience:

• Learn once, use everywhere
• IDE autocomplete just works
• Reduced cognitive load
• Fewer decisions to make

Your Marketplace's Golden Core

Different ecosystems need different cores. Here are examples:

Vue Marketplace might bundle:

{ id: 'core/vue-essentials' }
// → Pinia + Vitest + ESLint + Prettier + Valibot

Angular Marketplace might bundle:

{ id: 'core/angular-essentials' }
// → NgRx + Jest + TSLint + Prettier + class-validator

Company Marketplace might bundle:

{ id: 'core/acme-standards' }
// → Your state + Your testing + Your linting + Your validation

The principle is the same: Define the core technologies that ALL modules in your marketplace depend on, then bundle them for convenience.

What's NOT in the Golden Core

TanStack Query - Included separately via data-fetching/tanstack-query

• Why separate? Not all apps need server state management
• Simple apps (static sites) don't need it
• Gives users flexibility to opt-out

React Hook Form - Included separately via core/forms

• Why separate? Not all apps have forms
• Landing pages might not need forms
• Reduces bundle size for simple apps

UI Libraries - Always separate (shadcn/ui, MUI, etc.)

• Why separate? UI is Agnostic Edge (see above)
• Teams have existing design systems
• Maximum flexibility

Level 2 Personalization in Action

Remember Level 2 Personalization (technology choices)? The Golden Core is where you define YOUR essential technologies.

Our choice: Zustand + Vitest + ESLint + Prettier + Zod
Your choice: Whatever makes sense for your ecosystem or company

The CLI doesn't care - it executes blueprints for any technology.

Part 2.75: The Two Architectural Patterns

Before diving into the three-tier module system, it's crucial to understand the TWO architectural patterns our marketplace supports.

Pattern A: SDK-Driven 🔵

When to use: An external SDK provides all the business logic.

Architecture:

Adapter (SDK)
    ↓
SDK-Backend-Connector (replaces backend!)
    ↓
Tech-Stack (fallback hooks)
    ↓
Frontend (UI)

Example: Auth with Better Auth

1. Adapter: auth/better-auth - Universal Better Auth config
2. Connector: connectors/auth/better-auth-nextjs - Next.js integration + SDK hooks
   • This IS the backend! No features/auth/backend/ needed
3. Tech-Stack: features/auth/tech-stack - Schemas + fallback hooks
4. Frontend: features/auth/frontend/shadcn - UI components

What the connector provides:

{
  "provides": [
    "auth-backend-complete",       // ← Backend replacement
    "auth-sdk-native-hooks"        // ← authClient.useSession()
  ],
  "role": "sdk-backend-connector",
  "pattern": "sdk-driven"
}

What the tech-stack provides:

{
  "provides": [
    "auth-schemas",                // Zod validation
    "auth-stores",                 // UI state (modals, etc.)
    "auth-hooks-generic"           // Fallback fetch hooks (priority: 1)
  ],
  "role": "tech-stack-layer",
  "pattern": "tech-agnostic"
}

🔑 The Magic: Frontend imports from @/lib/auth and gets SDK hooks (priority 2) that override generic hooks (priority 1).

Used by: Auth (Better Auth), Payments (Stripe)

Pattern B: Custom-Logic 🟢

When to use: You have custom business logic not provided by SDKs.

Architecture:

Adapter (framework)
    ↓
Regular Connector (optional wiring)
    ↓
Backend-Feature (custom logic!)
    ↓
Tech-Stack (wraps backend)
    ↓
Frontend (UI)

Example: AI Chat

1. Adapter: ai/vercel-ai-sdk - Vercel AI SDK
2. Backend: features/ai-chat/backend/nextjs - Custom conversation logic
   • Custom API routes
   • Custom business logic (conversation history, contexts, etc.)
3. Tech-Stack: features/ai-chat/tech-stack - Wraps backend in TanStack Query hooks
4. Frontend: features/ai-chat/frontend/shadcn - Chat UI

What the backend provides:

{
  "provides": [
    "ai-chat-api",                 // Custom API routes
    "ai-chat-business-logic",      // Conversation logic
    "ai-chat-persistence"          // Database operations
  ],
  "role": "backend-feature",
  "pattern": "custom-logic"
}

What the tech-stack provides:

{
  "provides": [
    "ai-chat-schemas",             // Zod validation
    "ai-chat-stores",              // UI state
    "ai-chat-hooks-wrapper"        // Hooks that wrap backend APIs
  ],
  "role": "tech-stack-layer",
  "pattern": "tech-agnostic"
}

🔑 The Difference: Backend provides async functions, tech-stack wraps them in TanStack Query hooks.

Used by: AI Chat, Teams Management, Emailing

Pattern Decision Tree

Does an SDK provide ALL the business logic?
│
├─ YES → Use SDK-Driven Pattern
│         - Create SDK-Backend Connector
│         - NO backend/ folder in feature
│         - Connector provides "backend-complete"
│
└─ NO  → Use Custom-Logic Pattern
          - Create Backend-Feature
          - Backend contains custom logic
          - Tech-Stack wraps backend in hooks

Part 3: The Three-Tier Module System (Our Marketplace)

Important: This structure is our React marketplace's choice. Your marketplace can use a completely different organization. Remember Level 1 Personalization (module structure)!

We organize modules into three tiers:

Think of it as an industrial supply chain:

• Adapters = Universal SDK configurations (framework-agnostic)
• Connectors = SDK + Framework integrations (bridge adapters to frameworks)
• Features = Complete business capabilities (backend + tech-stack + frontend)

Tier 1: Adapters (Universal SDK Configuration)

Role: Configure ONE SDK in a framework-agnostic way.

Key Principle: Adapters provide universal SDK configuration that works with ANY framework.

Characteristics:

• ✅ Single Responsibility: One adapter = one SDK/technology
• ✅ Framework-Agnostic: No Next.js, no Remix, no framework-specific code
• ✅ Universal Configuration: Base setup that connectors build upon
• ✅ Importable: Connectors import adapter configs to extend them

Example: The drizzle Adapter

What it does:

1. Installs drizzle-orm and drizzle-kit
2. Creates basic drizzle.config.ts
3. Sets up schema directory structure
4. Adds database scripts to package.json

What it does NOT do:

• ❌ Doesn't integrate with Next.js
• ❌ Doesn't create API routes
• ❌ Doesn't generate hooks
• ❌ Knows nothing about your UI

Generated code example:

// drizzle.config.ts
import type { Config } from 'drizzle-kit';
 
export default {
  schema: './src/db/schema/*',
  out: './drizzle',
  driver: 'pg',
  dbCredentials: {
    connectionString: process.env.DATABASE_URL!,
  },
} satisfies Config;

Capabilities System:

Adapters declare what they provide:

{
  "capabilities": {
    "provides": ["database", "orm", "drizzle"],
    "requires": []
  }
}

This powers the CLI's intelligent dependency resolution.

Full catalog: Browse all adapters →

Tier 2: Connectors (SDK + Framework Integration)

Role: Bridge universal adapters with specific frameworks.

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

Characteristics:

• ✅ Requires Adapters: Declared in connector.json
• ✅ Framework-Specific: Integrates SDK with Next.js, Remix, etc.
• ✅ Imports From Adapters: Extends adapter configurations
• ✅ Can Override Tech-Stack: Provides SDK-native hooks (priority system)

The Critical Pattern: Adapter → Connector Flow

// Step 1: Adapter provides universal config
// adapters/auth/better-auth/config.ts
export const auth = betterAuth({
  database: { /* universal config */ },
  emailAndPassword: { enabled: true }
});
 
// Step 2: Connector imports and extends for Next.js
// connectors/auth/better-auth-nextjs/config.ts
import { auth as baseAuth } from '@/lib/auth/better-auth-config';
export const auth = betterAuth({
  ...baseAuth.options,
  plugins: [nextCookies()]  // ← Next.js specific
});

Example: The connectors/auth/better-auth-nextjs/ Connector

What it does:

1. Connects Drizzle (database) with Next.js (framework)
2. Scans your Drizzle schemas
3. Generates Next.js API routes for each table
4. Creates TanStack Query hooks (Golden Core API)
5. Sets up query client and providers

Generated API Route:

// Generated: src/app/api/products/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { db } from '@/db/client';
import { products } from '@/db/schema';
import { eq } from 'drizzle-orm';
 
// GET /api/products
export async function GET(request: NextRequest) {
  try {
    const searchParams = request.nextUrl.searchParams;
    const id = searchParams.get('id');
    
    if (id) {
      const [product] = await db.select()
        .from(products)
        .where(eq(products.id, id))
        .limit(1);
      return NextResponse.json(product || null);
    }
    
    const allProducts = await db.select().from(products);
    return NextResponse.json(allProducts);
  } catch (error) {
    return NextResponse.json(
      { error: 'Failed to fetch products' },
      { status: 500 }
    );
  }
}
 
// POST, PUT, DELETE methods also generated...

Generated TanStack Query Hook (Golden Core API):

// Generated: src/hooks/use-products.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import type { Product } from '@/db/schema';
 
// Query key factory
const productKeys = {
  all: ['products'] as const,
  detail: (id: string) => [...productKeys.all, id] as const,
};
 
/**
 * Fetch all products
 * Standard Golden Core pattern - TanStack Query
 */
export function useProducts() {
  return useQuery({
    queryKey: productKeys.all,
    queryFn: async (): Promise<Product[]> => {
      const res = await fetch('/api/products');
      if (!res.ok) throw new Error('Failed to fetch products');
      return res.json();
    },
    staleTime: 5 * 60 * 1000,
  });
}
 
/**
 * Create product
 * Includes automatic cache invalidation
 */
export function useCreateProduct() {
  const queryClient = useQueryClient();
  
  return useMutation({
    mutationFn: async (data: Omit<Product, 'id'>): Promise<Product> => {
      const res = await fetch('/api/products', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(data),
      });
      if (!res.ok) throw new Error('Failed to create product');
      return res.json();
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: productKeys.all });
    },
  });
}
 
// useUpdateProduct() and useDeleteProduct() also generated...

The Power: This exact pattern is generated for every table in your database. You get type-safe, cached, optimistic data hooks automatically.

Full catalog: Browse all connectors →

Tier 3: Features (Complete Business Capabilities)

Role: Deliver complete, user-facing business functionality.

Key Principle: Features are organized in 3 layers: Backend / Tech-Stack / Frontend.

Characteristics:

• ✅ Complete Functionality: Full user-facing capability
• ✅ 3-Layer Structure: Backend (optional) / Tech-Stack (contract) / Frontend (UI)
• ✅ Golden Core Compliant: Uses standardized patterns
• ✅ Swappable UI: Frontend can be changed without touching logic

The Backend / Tech-Stack / Frontend Pattern

This is our feature architecture. It provides clear separation of concerns:

Layer 1: Backend (features/[name]/backend/[framework]/)

• Optional layer - only if SDK doesn't provide everything
• Custom business logic not covered by adapters/connectors
• Feature-specific API routes
• Database operations
• Complex business rules

Example: features/teams-management/backend/nextjs/

• Custom team invitation logic
• Team analytics endpoints
• Invite acceptance workflows

Layer 2: Tech-Stack (features/[name]/tech-stack/)

• The contract layer - single source of truth
• Zod schemas (validation)
• TypeScript types (type safety)
• Generic hooks (TanStack Query fallbacks)
• UI-only stores (Zustand for modals, filters, preferences)
• NO framework-specific code
• Importable by both backend and frontend

Example: features/auth/tech-stack/

// schemas.ts - Zod validation
export const loginSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});
 
// types.ts - TypeScript types
export type LoginInput = z.infer<typeof loginSchema>;
export type User = { id: string; email: string; name: string };
 
// hooks.ts - Generic fallback hooks (priority: 1)
export function useSession() {
  return useQuery({
    queryKey: ['session'],
    queryFn: async () => {
      const res = await fetch('/api/auth/session');
      return res.json();
    }
  });
}
 
// stores.ts - UI-only state
export const useAuthUIStore = create((set) => ({
  showLoginModal: false,
  toggleLoginModal: () => set((s) => ({ showLoginModal: !s.showLoginModal })),
}));

Layer 3: Frontend (features/[name]/frontend/[ui-library]/)

• UI components only
• Imports from tech-stack layer
• Uses hooks, schemas, types from tech-stack
• Specific to UI library (shadcn, MUI, etc.)
• Can be swapped without touching business logic

Example: features/auth/frontend/shadcn/

// LoginForm.tsx
import { useSession } from '@/lib/auth';  // From tech-stack or connector
import { loginSchema } from '@/lib/auth/schemas';  // From tech-stack
import { Button } from '@/components/ui/button';  // shadcn/ui
 
export function LoginForm() {
  const { data: session } = useSession();
  // ... UI code using shadcn components
}

The "Backend Overwrites Hooks" Pattern

Connectors can provide SDK-native hooks that override generic tech-stack hooks:

Priority System:

// Priority 1: Tech-Stack (Generic Fallback)
// features/auth/tech-stack/hooks.ts
export function useSession() {
  // Generic fetch-based implementation
  return useQuery({ /* ... */ });
}
// Deployed to: src/lib/auth/hooks.ts (priority: 1)
 
// Priority 2: Connector (SDK-Native - OVERWRITES)
// connectors/auth/better-auth-nextjs/hooks.ts
export { useSession } from '@/lib/auth/client';  // Better Auth native
// Deployed to: src/lib/auth/hooks.ts (priority: 2) ← WINS!

Result: Frontend imports from @/lib/auth and gets the best implementation available (SDK-native if connector provides it, generic fallback otherwise).

Real-World Feature Examples

The Backend / Tech-Stack / Frontend structure handles different types of integrations:

1. SDK-Based Features (No Backend Needed)

• Example: Auth (Better Auth)
• SDK + connector provide everything
• Backend folder not needed

2. External API Features (Optional Backend)

• Example: Payments (Stripe)
• API handles core functionality
• Backend only for custom business logic

3. Custom Features (Backend Required)

• Example: Teams Management
• No SDK available
• Full backend with custom logic required

Deep Dive: For a comprehensive explanation of when to use backend, all integration patterns, and the Backend Overwrites Hooks pattern with real examples, see Features Deep Dive →

Full catalog: Browse all features →

Part 4: The Module Hierarchy in Practice

Let's see how all three tiers work together in a real scenario.

Example: Building a SaaS with Database & Auth

Step 1: Install Raw Materials (Adapters)

architech new my-saas --genome saas-starter

This installs base adapters:

• framework/nextjs - Next.js framework
• database/drizzle - Drizzle ORM
• ui/shadcn-ui - UI components
• auth/better-auth - Better Auth provider

Each adapter is isolated. Drizzle doesn't know about Next.js. Better Auth doesn't know about shadcn/ui.

Step 2: Connect Technologies (Connectors)

The genome also includes connectors:

• connectors/drizzle-nextjs - Connects database to framework
• connectors/tanstack-query-nextjs - Sets up data fetching
• connectors/better-auth-github - Connects auth with GitHub OAuth

Connectors bridge the adapters and generate integration code:

• API routes for each database table
• TanStack Query hooks (Golden Core)
• Auth routes and session management

Step 3: Add Business Capabilities (Features)

The genome includes features:

• features/auth/tech-stack - Headless auth logic
• features/auth/frontend/shadcn - Auth UI components
• features/auth/backend/better-auth-nextjs - Auth backend

Features compose the connectors into complete functionality users can interact with.

The Result:

• ✅ Full authentication system
• ✅ Database with type-safe API
• ✅ Beautiful UI components
• ✅ All following Golden Core patterns
• ✅ All in code you own and can customize

Part 5: Key Technical Concepts

Virtual File System (VFS)

The CLI uses an in-memory VFS for atomic, safe file operations:

Benefits:

• ✅ All changes in memory until commit
• ✅ Automatic rollback on errors
• ✅ Per-blueprint isolation
• ✅ No partial states

Example:

// All operations in memory
vfs.writeFile('package.json', newContent);
vfs.writeFile('tsconfig.json', newContent);
 
// Atomic commit - all or nothing
await vfs.flushToDisk();

Deep dive: VFS Architecture →

AST-Based Manipulation

The CLI uses ts-morph for reliable code modification:

Benefits:

• ✅ AST-aware, not regex-based
• ✅ Preserves code structure
• ✅ Handles complex TypeScript
• ✅ Type-safe transformations

Example:

// Add import to existing file
sourceFile.addImportDeclaration({
  moduleSpecifier: '@tanstack/react-query',
  namedImports: ['useQuery']
});

Deep dive: Modifier Layer →

Dependency Resolution

The CLI uses topological sort to execute modules in the correct order:

Example:

Dependencies:
- connector/drizzle-nextjs requires: [framework/nextjs, database/drizzle]
- database/drizzle requires: []
- framework/nextjs requires: []

Execution Order (calculated):
1. framework/nextjs (no dependencies)
2. database/drizzle (no dependencies)
3. connector/drizzle-nextjs (dependencies met)

Deep dive: Dependency Resolution →

Type-Safe Genomes

Genomes are TypeScript files with full IDE autocomplete:

import { defineGenome } from '@thearchitech.xyz/marketplace/types';
 
export default defineGenome({
  project: {
    name: 'my-app',
    framework: 'nextjs',
  },
  modules: [
    {
      id: 'framework/nextjs',  // ← Autocomplete available
      parameters: {
        typescript: true,      // ← Type-safe
        tailwind: true,        // ← Validated
      }
    }
  ]
});

See all genomes: Genome Catalog →

Part 6: The Architecture in Action

Scenario: AI Chat Application

Let's build a complete AI chat app to see how all tiers work together:

1. Raw Materials (Adapters):

# Foundation technologies (isolated)
- framework/nextjs      → Next.js framework
- database/drizzle      → Database ORM
- ai/vercel-ai-sdk      → AI provider
- ui/shadcn-ui          → UI components

2. Assembly Lines (Connectors):

# Integration code (bridges technologies)
- drizzle-nextjs           → DB + Framework = API routes + data hooks
- tanstack-query-nextjs    → Data fetching infrastructure
- zustand-nextjs           → State management setup

3. Finished Products (Features):

# Complete capabilities
- features/ai-chat/tech-stack          → Headless chat logic
- features/ai-chat/backend/vercel-ai   → Streaming endpoints
- features/ai-chat/frontend/shadcn     → Chat UI

What you get:

• ✅ Complete AI chat interface
• ✅ Message persistence (Drizzle)
• ✅ Real-time streaming (Vercel AI SDK)
• ✅ Beautiful UI (shadcn/ui)
• ✅ Type-safe throughout
• ✅ Following Golden Core patterns

All in ~30 minutes with one command.

Part 7: Why This Architecture Matters

Benefit 1: Maintainability

• Consistent patterns across your entire codebase
• Golden Core APIs mean you always know how data flows
• Clear separation between logic and presentation
• Easy onboarding for new team members

Benefit 2: Flexibility

• Swap UI libraries without touching business logic
• Change ORMs without rewriting features
• Migrate frameworks while keeping your code
• Add new capabilities without breaking existing ones

Benefit 3: Scalability

• Team members learn one set of patterns
• New features follow proven blueprints
• Codebase grows without chaos
• Code review becomes systematic

Benefit 4: Composability

• Features combine predictably
• No conflicts between modules
• Dependency resolution prevents breakage
• Standards emerge naturally

Next Steps

For Users (Using Our Marketplace)

• Getting Started → - Generate your first project
• Cookbook → - Practical recipes and patterns
• Modules Catalog → - Browse all available modules
• Troubleshooting → - Common issues and solutions

For Deep Divers (Understanding the CLI)

• CLI Internals → - Complete technical architecture
• Blueprint Actions → - How to write blueprints
• Design Decisions → - Why we made these choices

For Creators (Building Marketplaces)

• Creating Marketplaces → - Build your own marketplace
• Contributor Guide → - Add to our marketplace
• Contributing → - Complete contribution guidelines

This architecture is battle-tested, production-ready, and built for scale. Let's build something amazing.