Ixiptla - Archaeological Replicas Showcase

Description

Ixiptla is a modern web application that presents a curated collection of meticulously crafted archaeological reproductions. Built with Astro.js and React, this platform combines performance with stunning visual presentation to bring ancient replicas to life in the digital realm. The project features interactive 3D models using Three.js, fully responsive design, and comprehensive internationalization support in English and Spanish.

Challenges

Interactive 3D Model Integration: Implementing 3D model viewing capabilities that are performant across devices while maintaining visual fidelity presented significant technical challenges.
Bilingual Content Management: Creating a seamless content management system that maintains parity between English and Spanish translations while ensuring consistent metadata across language versions.
Performance Optimization: Balancing high-quality visual content and 3D interactivity with fast load times and responsive performance across devices.
Content Organization Architecture: Designing a flexible but rigorous schema for replica data that accommodates diverse archaeological items with varying attributes and metadata requirements.
Advanced UI Interactions: Implementing sophisticated UI features like advanced filtering, sorting, and visualization options for the replica collection.

Solutions

3D Model Implementation

I leveraged React Three Fiber and Drei to create an abstracted 3D scene component that handles model loading, camera controls, and lighting. The implementation includes:

// Scene3D component handles all Three.js setup
export function Scene3D({
  modelPath = "/images/models/colibri.glb",
}: Scene3DProps) {
  const [autoRotate, setAutoRotate] = useState(false);
  const controlsRef = useRef<OrbitControlsImpl>(null);

  // Custom event system for external controls
  useEffect(() => {
    const handleResetCamera = () => {
      if (controlsRef.current) {
        controlsRef.current.reset();
      }
    };

    window.addEventListener("reset-camera", handleResetCamera);
    // Additional event handlers...

    return () => {
      window.removeEventListener("reset-camera", handleResetCamera);
      // Cleanup...
    };
  }, []);

  // Canvas, lighting, controls setup...
}

Internationalization Architecture

I designed a robust i18n system using:

Language detection based on browser settings
URL-based language routing (/en/, /es/)
JSON-based translation files with nested keys
Custom translation utility functions

// Translation utility function
export function useTranslations(lang: "en" | "es") {
  const translations = lang === "es" ? es : en;

  return function t(key: string) {
    const keys = key.split(".");
    let value: any = translations;
    for (const k of keys) {
      value = value[k];
      if (value === undefined) return key;
    }

    return value as string;
  };
}

Content Schema and Organization

I implemented a strongly typed content schema using Zod for validation, ensuring data integrity across all replicas:

const replicaSchema = z.object({
  id: z.string(),
  title: z.string(),
  culture: z.string(),
  period: z.string(),
  image: z.string(),
  description: z.string(),
  museum: z.string(),
  location: z.string(),
  dimensions: z.string().optional(),
  material: z.string().optional(),
  technique: z.string().optional(),
  has3DModel: z.boolean().optional(),
  slug: z.string(),
});

This approach enforces content consistency while providing flexibility for optional attributes.

Performance Optimizations

To ensure optimal performance while maintaining visual quality:

Implemented responsive image loading with proper dimensions and WebP format
Used lazy loading for off-screen content
Optimized 3D model loading with suspense and fallbacks
Leveraged Astro’s partial hydration for minimal JavaScript

Results

Enhanced User Experience: Created an immersive platform with interactive 3D models that allows users to explore archaeological replicas from all angles.
Performance Metrics: Achieved excellent performance scores with load times under 3 seconds and Largest Contentful Paint under 2.5 seconds, even with complex 3D content.
Accessibility & Internationalization: Delivered a fully bilingual experience with comprehensive accessibility features, making archaeological content available to a broader audience.
Maintainable Architecture: Established a flexible yet robust content schema and component architecture that facilitates seamless addition of new replicas and content updates.
Responsive Design: Ensured a consistent experience across all devices, from mobile to desktop, with thoughtful responsive design implementations.