AI Prompt: Forma3D.Connect — Full Multi-Tenancy + Super Admin¶

// ❌ WRONG - can modify any tenant's data
await prisma.order.update({
  where: { id },
  data: { status },
});

// ✅ CORRECT - enforces tenant isolation
await prisma.order.update({
  where: { id, tenantId }, // Compound where
  data: { status },
});

export interface OrderDto {
  id: string;
  tenantId: string; // ← REQUIRED
  shopifyOrderId: string;
  // ... rest of fields
}

apps/api/src/
├── auth/
│   ├── decorators/
│   │   ├── current-user.decorator.ts      # UPDATE: include activeTenantId
│   │   └── require-super-admin.decorator.ts  # NEW
│   ├── guards/
│   │   └── super-admin.guard.ts           # NEW
│   └── services/
│       └── auth.service.ts                # UPDATE: handle super admin session
│
├── tenancy/
│   ├── dto/
│   │   ├── tenant.dto.ts                  # NEW: tenant response DTO
│   │   ├── create-tenant.dto.ts           # NEW: create tenant input
│   │   └── switch-tenant.dto.ts           # NEW: switch tenant input
│   ├── tenants.controller.ts              # NEW: tenant management endpoints
│   ├── tenants.service.ts                 # NEW: tenant business logic
│   ├── tenants.repository.ts              # NEW: tenant data access
│   ├── tenant-context.service.ts          # UPDATE: support super admin context
│   └── tenancy.module.ts                  # UPDATE: export new services
│
├── orders/
│   ├── orders.repository.ts               # UPDATE: add tenantId to all methods
│   ├── orders.service.ts                  # UPDATE: pass tenantId from context
│   └── orders.controller.ts               # UPDATE: inject TenantContext
│
├── print-jobs/
│   ├── print-jobs.repository.ts           # UPDATE: add tenantId to all methods
│   └── print-jobs.service.ts              # UPDATE: pass tenantId from context
│
├── shipments/
│   ├── shipments.repository.ts            # UPDATE: add tenantId to all methods
│   └── shipments.service.ts               # UPDATE: pass tenantId from context
│
├── fulfillment/
│   └── fulfillment.service.ts             # UPDATE: use OrderDto with tenantId
│
└── shopify/
    └── shopify-webhook.service.ts         # UPDATE: resolve tenant from shop domain

libs/domain-contracts/src/lib/
├── types.ts                               # UPDATE: add tenantId to all DTOs
└── contracts/
    └── tenant.contracts.ts                # NEW: tenant-related interfaces

apps/web/src/
├── auth/
│   ├── auth-context.tsx                   # UPDATE: include activeTenantId, isSuperAdmin
│   └── hooks/
│       └── use-auth.ts                    # UPDATE: expose tenant switching
│
├── components/
│   └── tenant-switcher/
│       ├── tenant-switcher.tsx            # NEW: dropdown to switch tenants
│       └── tenant-switcher.api.ts         # NEW: API calls for tenant switching
│
├── pages/
│   ├── admin/
│   │   └── tenants/
│   │       ├── tenants-list.tsx           # NEW: list all tenants (super admin)
│   │       ├── tenant-create.tsx          # NEW: create tenant form
│   │       └── tenant-detail.tsx          # NEW: view/edit tenant
│   └── layout/
│       └── header.tsx                     # UPDATE: show tenant switcher for super admin
│
└── router.tsx                             # UPDATE: add tenant management routes

prisma/
├── schema.prisma                          # UPDATE: add isSuperAdmin to User
├── seed.ts                                # UPDATE: create super admin user
└── migrations/                            # NEW: migration for isSuperAdmin

model User {
  id            String   @id @default(uuid())
  tenantId      String   // Home tenant (for regular users)
  email         String   @unique
  passwordHash  String
  name          String?

  // Super Admin flag - allows cross-tenant access
  isSuperAdmin  Boolean  @default(false)

  // Session state for super admin (which tenant they're currently viewing)
  // Note: This is stored in session, not in User table

  roles         UserRole[]
  // ... rest of relations
}

interface UserSession {
  userId: string;
  email: string;
  tenantId: string; // User's home tenant
  isSuperAdmin: boolean;
  activeTenantId: string; // Currently active tenant (for super admin, can differ from tenantId)
  roles: string[];
  permissions: string[];
}

@Injectable({ scope: Scope.REQUEST })
export class TenantContextService {
  private tenantId: string | null = null;

  constructor(@Inject(REQUEST) private readonly request: Request) {
    // Resolve tenant from authenticated session
    const user = this.request.user as UserSession | undefined;

    if (user) {
      // For super admin, use activeTenantId (which they can switch)
      // For regular users, use their tenantId
      this.tenantId = user.isSuperAdmin ? user.activeTenantId : user.tenantId;
    }
  }

  getCurrentTenantId(): string {
    if (!this.tenantId) {
      throw new UnauthorizedException('No tenant context available');
    }
    return this.tenantId;
  }

  // For super admin to verify they can access a specific tenant
  canAccessTenant(tenantId: string): boolean {
    const user = this.request.user as UserSession | undefined;
    if (!user) return false;
    if (user.isSuperAdmin) return true;
    return user.tenantId === tenantId;
  }
}

import { Injectable, CanActivate, ExecutionContext, ForbiddenException } from '@nestjs/common';

@Injectable()
export class SuperAdminGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    const user = request.user;

    if (!user?.isSuperAdmin) {
      throw new ForbiddenException('Super Admin access required');
    }

    return true;
  }
}

@ApiTags('Tenants')
@Controller('api/v1/tenants')
@UseGuards(SessionGuard)
export class TenantsController {
  constructor(
    private readonly tenantsService: TenantsService,
    private readonly authService: AuthService
  ) {}

  @Get()
  @UseGuards(SuperAdminGuard)
  @ApiOperation({ summary: 'List all tenants (Super Admin only)' })
  async listTenants(): Promise<TenantDto[]> {
    return this.tenantsService.findAll();
  }

  @Post()
  @UseGuards(SuperAdminGuard)
  @ApiOperation({ summary: 'Create a new tenant (Super Admin only)' })
  async createTenant(@Body() dto: CreateTenantDto): Promise<TenantDto> {
    return this.tenantsService.create(dto);
  }

  @Get(':id')
  @UseGuards(SuperAdminGuard)
  @ApiOperation({ summary: 'Get tenant details (Super Admin only)' })
  async getTenant(@Param('id') id: string): Promise<TenantDto> {
    return this.tenantsService.findById(id);
  }

  @Post('switch')
  @UseGuards(SuperAdminGuard)
  @ApiOperation({ summary: 'Switch active tenant (Super Admin only)' })
  async switchTenant(
    @Body() dto: SwitchTenantDto,
    @CurrentUser() user: UserSession,
    @Res({ passthrough: true }) res: Response
  ): Promise<{ success: boolean; activeTenantId: string }> {
    // Update session with new active tenant
    await this.authService.updateActiveTenant(user.userId, dto.tenantId, res);
    return { success: true, activeTenantId: dto.tenantId };
  }

  @Get('current')
  @ApiOperation({ summary: 'Get current active tenant' })
  async getCurrentTenant(@CurrentUser() user: UserSession): Promise<TenantDto> {
    const tenantId = user.isSuperAdmin ? user.activeTenantId : user.tenantId;
    return this.tenantsService.findById(tenantId);
  }
}

@Injectable()
export class OrdersRepository {
  constructor(private readonly prisma: PrismaService) {}

  // ✅ CORRECT: tenantId required, used in where clause
  async findById(tenantId: string, id: string): Promise<Order | null> {
    return this.prisma.order.findFirst({
      where: { id, tenantId }, // Always include tenantId
    });
  }

  // ✅ CORRECT: tenantId in compound where for update
  async updateStatus(tenantId: string, id: string, status: OrderStatus): Promise<Order> {
    return this.prisma.order.update({
      where: { id, tenantId }, // Ensures tenant isolation
      data: { status, updatedAt: new Date() },
    });
  }

  // ✅ CORRECT: findMany always filtered by tenant
  async findAll(tenantId: string, options: FindOrdersOptions): Promise<Order[]> {
    return this.prisma.order.findMany({
      where: {
        tenantId, // Always filter by tenant
        ...options.filters,
      },
      orderBy: options.orderBy,
      take: options.limit,
      skip: options.offset,
    });
  }

  // ✅ CORRECT: delete also requires tenant verification
  async delete(tenantId: string, id: string): Promise<void> {
    await this.prisma.order.deleteMany({
      where: { id, tenantId },
    });
  }
}

export interface OrderDto {
  id: string;
  tenantId: string; // ← ADD THIS
  shopifyOrderId: string;
  shopifyOrderNumber: string;
  status: OrderStatusType;
  customerName: string;
  customerEmail: string | null;
  shippingAddress: unknown;
  trackingNumber: string | null;
  trackingUrl: string | null;
  shopifyFulfillmentId: string | null;
  totalParts: number;
  completedParts: number;
  createdAt: Date;
  updatedAt: Date;
}

export interface LineItemDto {
  id: string;
  tenantId: string; // ← ADD THIS
  orderId: string;
  shopifyLineItemId: string;
  productSku: string;
  productName: string;
  variantTitle: string | null;
  quantity: number;
  status: LineItemStatusType;
  totalParts: number;
  completedParts: number;
}

export interface PrintJobDto {
  id: string;
  tenantId: string; // ← ADD THIS
  lineItemId: string;
  simplyPrintJobId: string | null;
  status: PrintJobStatusType;
  printerId: string | null;
  printerName: string | null;
  fileUrl: string | null;
  fileName: string | null;
  progress: number;
  errorMessage: string | null;
  startedAt: Date | null;
  completedAt: Date | null;
}

export interface ShipmentDto {
  id: string;
  tenantId: string; // ← ADD THIS
  orderId: string;
  sendcloudParcelId: string | null;
  carrier: string | null;
  trackingNumber: string | null;
  trackingUrl: string | null;
  labelUrl: string | null;
  status: ShipmentStatusType;
  createdAt: Date;
  updatedAt: Date;
}

@Injectable()
export class ShopifyWebhookService {
  constructor(
    private readonly shopRepository: ShopifyShopRepository,
    private readonly ordersService: OrdersService,
    private readonly logger: Logger
  ) {}

  async handleOrderCreated(
    shopDomain: string, // From x-shopify-shop-domain header
    payload: ShopifyOrderPayload
  ): Promise<void> {
    // Resolve tenant from shop domain
    const shop = await this.shopRepository.findByDomain(shopDomain);

    if (!shop) {
      this.logger.warn(`Received webhook for unknown shop: ${shopDomain}`);
      throw new NotFoundException(`Shop not found: ${shopDomain}`);
    }

    if (!shop.isActive) {
      this.logger.warn(`Received webhook for inactive shop: ${shopDomain}`);
      throw new BadRequestException(`Shop is inactive: ${shopDomain}`);
    }

    const tenantId = shop.tenantId;

    // Process order with resolved tenant context
    await this.ordersService.createFromShopify(tenantId, payload);
  }
}

@Controller('api/v1/webhooks/shopify')
export class ShopifyWebhookController {
  @Post('orders/create')
  async handleOrderCreated(
    @Headers('x-shopify-shop-domain') shopDomain: string,
    @Headers('x-shopify-hmac-sha256') hmac: string,
    @Body() payload: ShopifyOrderPayload
  ): Promise<void> {
    // Validate HMAC (existing logic)
    await this.validateHmac(hmac, payload);

    // Route to tenant based on shop domain
    await this.webhookService.handleOrderCreated(shopDomain, payload);
  }
}

import { useState, useEffect } from 'react';
import { useAuth } from '@/auth/hooks/use-auth';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from '@/components/ui/select';

interface Tenant {
  id: string;
  name: string;
  slug: string;
}

export function TenantSwitcher() {
  const { user, isSuperAdmin, activeTenantId, switchTenant } = useAuth();
  const [tenants, setTenants] = useState<Tenant[]>([]);
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    if (isSuperAdmin) {
      fetchTenants();
    }
  }, [isSuperAdmin]);

  const fetchTenants = async () => {
    const response = await fetch('/api/v1/tenants', {
      credentials: 'include',
    });
    if (response.ok) {
      setTenants(await response.json());
    }
  };

  const handleTenantChange = async (tenantId: string) => {
    setIsLoading(true);
    try {
      await switchTenant(tenantId);
      // Refresh page to load new tenant's data
      window.location.reload();
    } finally {
      setIsLoading(false);
    }
  };

  if (!isSuperAdmin) {
    return null;
  }

  return (
    <div className="flex items-center gap-2">
      <span className="text-sm text-muted-foreground">Tenant:</span>
      <Select value={activeTenantId} onValueChange={handleTenantChange} disabled={isLoading}>
        <SelectTrigger className="w-48">
          <SelectValue placeholder="Select tenant" />
        </SelectTrigger>
        <SelectContent>
          {tenants.map((tenant) => (
            <SelectItem key={tenant.id} value={tenant.id}>
              {tenant.name}
            </SelectItem>
          ))}
        </SelectContent>
      </Select>
    </div>
  );
}

interface AuthContextValue {
  user: User | null;
  isAuthenticated: boolean;
  isSuperAdmin: boolean;
  activeTenantId: string | null;
  login: (email: string, password: string) => Promise<void>;
  logout: () => Promise<void>;
  switchTenant: (tenantId: string) => Promise<void>;
}

export function AuthProvider({ children }: { children: React.ReactNode }) {
  const [user, setUser] = useState<User | null>(null);
  const [activeTenantId, setActiveTenantId] = useState<string | null>(null);

  const switchTenant = async (tenantId: string) => {
    const response = await fetch('/api/v1/tenants/switch', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      credentials: 'include',
      body: JSON.stringify({ tenantId }),
    });

    if (response.ok) {
      const data = await response.json();
      setActiveTenantId(data.activeTenantId);
    }
  };

  const value: AuthContextValue = {
    user,
    isAuthenticated: !!user,
    isSuperAdmin: user?.isSuperAdmin ?? false,
    activeTenantId,
    login,
    logout,
    switchTenant,
  };

  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
}

import { TenantSwitcher } from '@/components/tenant-switcher/tenant-switcher';
import { useAuth } from '@/auth/hooks/use-auth';

export function Header() {
  const { user, isSuperAdmin } = useAuth();

  return (
    <header className="border-b">
      <div className="flex items-center justify-between px-6 py-4">
        <div className="flex items-center gap-4">
          <Logo />
          {isSuperAdmin && <TenantSwitcher />}
        </div>
        <div className="flex items-center gap-4">
          <UserMenu user={user} />
        </div>
      </div>
    </header>
  );
}

# Database
pnpm prisma migrate dev
pnpm prisma db seed

# Build
pnpm nx build api
pnpm nx build web

# Lint + tests
pnpm lint
pnpm test
pnpm nx test acceptance-tests

# Create super admin (after seed)
# Super admin should exist from seed, or create via:
# UPDATE "User" SET "isSuperAdmin" = true WHERE email = 'admin@forma3d.be';