Hexa Shop

Project Overview

Hexa Shop is a modern, full-stack e-commerce platform built with the latest web technologies. The application features a customer-facing storefront and a comprehensive admin dashboard for managing products, categories, orders, and store settings.

The platform was designed with scalability, developer experience, and modern UX patterns in mind, leveraging React Server Components for optimal performance and Supabase for a complete backend-as-a-service solution.

Key Features

• 🛒 Customer Storefront — Browse products, categories, and complete purchases
• 📊 Admin Dashboard — Full CRUD operations for products, categories, inventory, and orders
• 🔐 Role-Based Access Control — Admin, demo admin (limited write access), and customer roles
• 🖼️ Image Management — Multi-image uploads with Supabase Storage integration
• 🎨 Dark/Light Theme — System-aware theme switching with persistent preferences
• 📱 Responsive Design — Mobile-first approach with collapsible sidebar navigation

Technologies Used

Frontend

Backend & Infrastructure

Development Tools

Challenges Faced

1. Supabase Client Caching in Serverless Environment

Problem: Next.js 16's Fluid compute architecture caused issues when caching Supabase clients at module level, leading to stale authentication states and cookie synchronization problems.

Impact: Users experienced intermittent auth failures and session inconsistencies across server components and server actions.

2. Complex Role-Based Permissions

Problem: The application required granular permissions with three distinct roles:

• Admin — Full access to all operations
• Demo Admin — Read access + create/update (no delete) for portfolio demonstrations
• Customer — Public storefront access only

Impact: Needed a flexible authorization system that could be checked both in middleware (route protection) and server actions (operation-level protection).

3. Multi-Image Product Management

Problem: Products required multiple images with primary image designation, reordering capability, and proper cleanup when images are deleted or replaced.

Impact: Required coordination between React state, form handling, Supabase Storage uploads, and database transactions.

4. Optimistic UI with Server State

Problem: Balancing immediate UI feedback with server-side data consistency when performing CRUD operations through server actions.

Impact: Users expected instant feedback while the system needed to maintain data integrity and handle potential failures gracefully.

Solutions Implemented

1. Fresh Supabase Client Pattern

Implemented a strict "create fresh per function" pattern for server-side Supabase clients:

// lib/supabase/server.ts
export async function createClient() {
  const cookieStore = await cookies();
  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
    {
      cookies: {
        getAll: () => cookieStore.getAll(),
        setAll: (cookiesToSet) => {
          cookiesToSet.forEach(({ name, value, options }) =>
            cookieStore.set(name, value, options)
          );
        },
      },
    }
  );
}

Every server action and API route creates a new client instance, ensuring proper cookie handling and authentication state.

2. Layered Authorization System

Implemented a multi-layer approach:

Layer 1 — Middleware Route Protection:

// proxy.ts
export const config = {
  matcher: ["/admin/:path*"],
};

Layer 2 — Role Helper Functions:

// lib/auth/roles.ts
export function isAdmin(user: User | null): boolean {
  return user?.app_metadata?.role === "admin";
}
 
export function hasAdminAccess(user: User | null): boolean {
  return isAdmin(user) || isDemoAdmin(user);
}

Layer 3 — Server Action Guards:

export async function deleteCategory(id: string) {
  const supabase = await createClient();
  const {
    data: { user },
  } = await supabase.auth.getUser();
 
  // Only full admin can delete
  if (!isAdmin(user)) {
    return { ok: false, error: "Only admin users can delete records" };
  }
  // ... proceed with deletion
}

3. TanStack Query Integration with Server Actions

Combined TanStack Query's caching capabilities with Next.js Server Actions:

// hooks/use-categories.ts
export function useAddCategory() {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: async (formData: FormData) => {
      const result = await addCategory(formData);
      if (!result.ok) throw new Error(result.error);
      return result;
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: CATEGORIES_QUERY_KEY });
      toast.success("Category created!");
    },
    onError: (error: Error) => toast.error(error.message),
  });
}

This pattern provides:

• Automatic cache invalidation on mutations
• Loading and error states
• Optimistic updates when needed
• Toast notifications for user feedback

4. Composable Form Architecture

Standardized form pattern using React Hook Form with Zod validation:

// Separate schema file
export const categoryFormSchema = z.object({
  name: z.string().min(1, "Required").max(100),
  is_active: z.boolean(),
});
 
// Form component with Controller pattern
<Controller
  control={control}
  name="name"
  render={({ field, fieldState }) => (
    <Field data-invalid={fieldState.invalid}>
      <FieldLabel htmlFor="name">Name</FieldLabel>
      <Input {...field} />
      {fieldState.invalid && <FieldError errors={[fieldState.error]} />}
    </Field>
  )}
/>;

Architecture Highlights

Directory Structure

app/
├── (root)/          # Public storefront (route group)
├── admin/           # Protected admin dashboard
├── auth/            # Authentication flows
└── actions/         # Shared server actions

lib/
├── services/        # Server actions (categories.ts, products.ts)
├── supabase/        # Client factories (server.ts, client.ts)
└── auth/            # Role helpers

components/
├── ui/              # shadcn/ui primitives
├── admin/           # Admin-specific components
└── auth/            # Auth forms

hooks/               # TanStack Query hooks
providers/           # React context providers

Data Flow

User Action → React Hook Form → Server Action → Supabase
     ↓
TanStack Query Mutation → Cache Invalidation → UI Update
     ↓
Toast Notification (Sonner)

Results Achieved

Performance Metrics

• ⚡ First Contentful Paint: < 1.5s with React Server Components
• 📦 Bundle Size: Optimized with tree-shaking and dynamic imports
• 🔄 Data Fetching: Efficient with TanStack Query deduplication and caching

Developer Experience

• ✅ 100% TypeScript: End-to-end type safety from database to UI
• 🧩 Modular Architecture: Clear separation of concerns
• 📝 Consistent Patterns: Standardized forms, hooks, and server actions

User Experience

• 🎯 Instant Feedback: Optimistic updates with graceful error handling
• 🌓 Theme Support: Seamless dark/light mode switching
• 📱 Responsive: Full functionality on mobile devices

Security

• 🔒 Multi-layer Auth: Middleware + server-side role checks
• 🛡️ Demo Mode: Safe demonstration without data loss risk
• 🔐 Secure Uploads: Validated file types and size limits

Key Learnings

1. Serverless Architecture Requires Stateless Patterns: Module-level caching can cause subtle bugs in serverless environments. Always create fresh instances for request-scoped resources.

2. Type Safety Pays Off: The upfront investment in TypeScript and Zod schemas prevented countless runtime errors and improved refactoring confidence.

3. Separation of Server/Client Concerns: Clear boundaries between server and client code (Server Actions vs TanStack Query hooks) made the codebase more maintainable.

4. Component Composition Over Configuration: Building with shadcn/ui's composable primitives allowed for consistent yet flexible UI patterns.

Links

• 🔗 Live Demo — Try the demo admin experience
• 📂 GitHub Repository — View the source code
• 📧 Contact — Discuss this project

Built with Next.js 16, React 19, Supabase, and modern web technologies.