System Modules
Carto-Art
A full-stack cartographic design platform that transforms geographic data into gallery-quality map art, with integrated e-commerce, 3D terrain visualization, and social features.
Overview
Carto-Art began as a frontend-only prototype inspired by a street vendor selling simple map prints. The realization that a more powerful, customizable tool could bridge the gap between technical GIS data and aesthetic interior decor led to its creation. Since then, it has evolved into a complete platform: users can design maps with true 3D terrain, order physical prints shipped directly to their door, and share their creations with a community of cartography enthusiasts.
Technical Architecture
Carto-Art is built on Next.js 14+ (App Router) with TypeScript, combining a responsive React frontend with robust backend services. Map rendering uses MapLibre GL JS for vector base maps, now augmented with Deck.gl for true 3D volumetric terrain. The UI leverages Tailwind CSS and shadcn/ui components.
The backend runs on Supabase, providing PostgreSQL with Row Level Security, authentication (Google and GitHub providers), and file storage. The e-commerce pipeline integrates Stripe for payments, Printful for print-on-demand fulfillment, and Resend for transactional emails.
This architectural evolution from pure frontend to full-stack was driven by the need for e-commerce integration, user accounts with saved designs, and laying the groundwork for future features like a developer API.
3D Volumetric Terrain
The original hillshading system has been upgraded to true 3D terrain visualization using Deck.gl's TerrainLayer.
Elevation Data: The system fetches AWS Terrarium tiles, where each pixel's RGB values encode elevation with 0.1-meter precision. Users can adjust vertical exaggeration (0-5x) to emphasize topography, control sun positioning for dynamic lighting effects, and select mesh quality presets ranging from "Fast" to "Ultra."
WebGL Context Sharing: The key to seamless integration is the MapboxOverlay from @deck.gl/mapbox with interleaved: true. This forces Deck.gl to share the same WebGL2 context as MapLibre—same depth buffer, same projection matrix. MapLibre drives the camera, and Deck.gl automatically renders the terrain mesh in the correct coordinate space. No manual frame-by-frame synchronization required.
Performance Management: Rendering dense 3D meshes in the browser demands careful optimization. The meshMaxError parameter controls triangle density, with quality presets letting users balance visual detail against framerate. A zoom offset cap prevents tile request explosions at high zoom levels, and the default "Balanced" preset avoids the memory issues that can crash mobile browsers at "Ultra" settings.
High-Resolution Export Engine
Unlike many web map tools limited to screen-resolution screenshots, Carto-Art renders at true print quality—up to 24×36 inches at 300 DPI (7200×10800 pixels). This capability required solving a fundamental architectural challenge: the export resolution far exceeds what can be displayed on screen, and the 3D terrain system that works beautifully for interactive viewing cannot scale to 8K+ resolutions.
Dual Render Paths: The solution is a strict separation between live preview and static export. For high-resolution PNG exports, the system spawns a headless map instance off-screen, sized to the target physical dimensions. Critically, 3D terrain is disabled for these exports—allocating a WebGL context at 8K resolution with a dense terrain mesh exceeds the texture size and memory limits of consumer GPUs, causing "Context Lost" errors. The static export uses a top-down flat style optimized for large-format print.
Video/GIF Export: For animated exports, the system captures the live canvas using createImageBitmap. Because this uses the shared WebGL context, 3D terrain is included—but resolution is limited to screen dimensions. This trade-off gives users both options: infinite-resolution flat prints or screen-resolution 3D animations.
E-Commerce & Print Fulfillment
A complete direct-to-consumer flow lets users go from design to physical print.
The Pipeline: When a user finalizes their design, the high-resolution PNG uploads to a private Supabase Storage bucket, generating a 24-hour signed URL. This URL attaches to the Stripe PaymentIntent metadata, persisting through the payment lifecycle. When the payment_intent.succeeded webhook fires, the system reads the design URL from metadata and passes it directly to Printful's API for fulfillment.
Intelligent Mockup Generation: Printful's mockup generator API is wrapped with a custom intelligence layer that solves the orientation problem. A 12×18 landscape map on an 18×12 portrait template looks wrong. The system parses variant names to calculate target aspect ratios, scans available templates, and selects the one with the closest matching print area. Exponential backoff handles Printful's rate limits gracefully.
Defensive Error Handling: The webhook checks order status before processing to prevent duplicate Printful orders. Fulfillment failures (resolution too low, out of stock) update the local order status and preserve error details for admin visibility. Email sending is resilient—failures are logged but don't break the webhook, ensuring orders are always recorded correctly.
Social Features & Community
Carto-Art includes a full social layer for sharing and discovering map designs.
Gallery: A public gallery displays published maps. Users can browse, vote on designs they like, and leave comments. Each gallery item links to the original creator's profile.
Remix Flow: The "Edit Copy" button opens a fresh editor pre-loaded with the original map's complete state—color scheme, layer configuration, camera position, everything. This lowers the barrier to experimentation and helps new users learn by building on existing designs.
User Profiles: Each user has a public profile showcasing their creations, including three featured maps they can pin to highlight their best work.
Advanced Annotation Tools
Users can annotate their maps with professional-grade vector overlays.
Custom Markers: Fully customizable icons, colors, and labels placed via the map interface.
Route Drawing: A "Connect Points" toggle creates LineString GeoJSON features linking markers sequentially, with real-time Haversine distance calculations displayed along each segment.
Area Filling: Closing a path creates a polygon with configurable fill opacity and color. All annotations support multiple rendering styles including "Vintage," "Glass," and "Elevated."
User Accounts & Subscriptions
Authentication: Supabase Auth with Google and GitHub providers.
Data Model: User profiles store subscription status and preferences. Saved map designs and order history persist across sessions.
Carto Plus: A subscription tier unlocks advanced features including premium export formats and additional map styles, managed through Stripe subscription webhooks.
Style Library
Carto-Art ships with an extensible style library including themes like Minimal Line Art, Dark Mode/Noir, and Blueprint/Technical. Each style includes recommended font pairings and color palettes, but users retain full control through the dynamic color swapping. Real-time adjustments propagate instantly without map reloads, enabling rapid iteration on compositions.
Results
What started as a weekend project has grown into a complete platform: 3D terrain visualization, print-on-demand e-commerce, and a social layer for sharing and remixing designs. The architecture balances ambition with pragmatism—3D terrain enhances interactive exploration while gracefully falling back for high-resolution exports, and the e-commerce pipeline handles real-world edge cases defensively. Try it at cartoart.net.