My fun christmas project for this year

bzddbz — Fri, 28 Nov 2025 20:37:12 +0000

North Pole Library – Technical Overview

1. Executive Summary

North Pole Library is a modern, AI-powered web application that allows users to create personalized Christmas stories for children. The platform leverages a sophisticated stack of cloud services, generative AI models, and automation workflows to deliver a seamless "text-to-storybook" experience. Users provide basic details (child's name, age, theme), complete a secure payment, and receive a fully illustrated, narrated, and interactive digital storybook within minutes.

2. Architecture & Technology Stack

The system is built on a Serverless Architecture, utilizing a decoupled frontend and an event-driven backend orchestrated by n8n.

Frontend Application

Core Framework:
Built with React (Vite) and TypeScript, ensuring type safety and high performance.

UI/UX:
Tailwind CSS is used for a responsive, mobile-first design system.
Framer Motion powers complex animations, including the "magical" snow effects, page transitions, and the interactive FlipBook component that simulates reading a physical book.

State Management: React Context API handles global application state, such as multi-language support (English/Hungarian) and user session data.
Hosting: The frontend is optimized for edge deployment (e.g., Vercel).
Backend & Database (Supabase)

Supabase serves as the backend-as-a-service (BaaS) layer, providing:

PostgreSQL Database: The stories table acts as the central source of truth, storing:

User inputs (Child's name, age, theme).
Order status (pending_payment, processing, completed).
The structured JSON content of the generated story.

Object Storage:
A dedicated story-assets bucket stores the generated media assets (images and MP3 audio files) for long-term persistence and fast CDN delivery.

Realtime/Polling:
The frontend polls the database status to provide real-time feedback to the user in the "Waiting Room" while the AI generation is in progress.

3. Core Workflows & Automation
The heart of the application is an event-driven automation pipeline managed by n8n. This workflow orchestrates the complex interaction between payments, AI generation, and database updates.

A. Payment & Initiation Flow
User Input: The user submits the story details via the
CreateStoryFlow
component.
Draft Creation: A record is created in Supabase with a pending_payment status.
Stripe Integration: The user is redirected to a Stripe Checkout session. The Story ID is passed as a client_reference_id to ensure the payment is inextricably linked to the specific story request.

B. The "Magic" Generation Pipeline (n8n)
Upon successful payment, Stripe triggers a webhook that starts the n8n workflow:

Data Retrieval: The workflow fetches the pending story details from Supabase using the ID from the payment event.
AI Text Generation (LLM):
The system prompts a Large Language Model (e.g., Google Gemini or OpenAI) to write a multi-page creative story based on the child's age, name, and chosen theme.
The output is structured as a JSON object containing text for each page and prompts for illustrations.

AI Image Generation:
The workflow iterates through the page prompts and calls an AI image generation service (e.g., Pollinations.ai) to create consistent, style-matched illustrations for every page.
Text-to-Speech (TTS) Generation:
Simultaneously, the text for each page is sent to a TTS engine (e.g., OpenAI Audio API) to generate high-quality voice narration.

Asset Management:
All generated images and audio files are uploaded to Supabase Storage.
Public URLs for these assets are generated and injected back into the story's JSON structure.

Finalization:
The fully assembled story object is updated in the Supabase database.
The status is set to completed.

C. Delivery
Email Notification: The n8n workflow sends a localized HTML email (English or Hungarian) to the user, containing a direct link to their personalized story.
Frontend Update: The user's waiting screen detects the completed status and automatically opens the interactive FlipBook.

4. Key Features Summary
Full Automation: Zero manual intervention required from payment to delivery.
Multi-Modal AI: Combines text, image, and audio generation into a cohesive product.
Localization: Built-in support for multiple languages in both the UI and the generated content.

Scalability: The use of serverless functions (Supabase) and async workflows (n8n) allows the system to handle high traffic volumes during peak holiday seasons without infrastructure management.

Demo:
https://www.youtube.com/watch?v=NDbKKT3fqOI

DEV Community: bzddbz

My fun christmas project for this year

North Pole Library – Technical Overview

1. Executive Summary

2. Architecture & Technology Stack