how it works
technical deep dive
Here's the technical breakdown of how your digital postcard becomes a physical one.
1. Storage & Database
When you submit your photo and message, the image is sent to our backend API.
The image is then uploaded to Supabase Storage in a dedicated bucket. Each file gets a unique name to prevent collisions and ensure uniqueness. Supabase returns a public URL for the uploaded image.
A new record is created in Supabase to store your postcard information, including the image URL, your name, message, and initial status. This record serves as our source of truth and allows us to track the postcard through its lifecycle.
2. PostGrid API - Physical Postcard Creation
This is where the magic happens. We use PostGrid, a mass mailing API service that handles the printing and physical mailing of postcards.
We construct an API request to PostGrid with:
- Front: Your uploaded image
- Back: Your message and signature, formatted with the Caveat font to mimic handwritten text. All user input is HTML-escaped to prevent XSS attacks.
- Recipient Address: The destination address for mailing
- Size: Standard 6x4 inch US postcard format
- Mailing Class: First class mail
PostGrid processes this request, prints the postcard on physical stock, and handles the mailing through the USPS. They return a tracking ID and status that we store in our database.
3. Database Status Update & Error Handling
Once PostGrid confirms the postcard creation, we update the database record with the tracking ID, status, and timestamp.
Resilience Design: If PostGrid API fails, the postcard is still saved in our database with a pending status. This allows for retry mechanisms or manual intervention later. The user still gets a success response, ensuring a smooth experience even if the mailing service is temporarily unavailable.
4. Additional Features
Security: All user-generated content (messages, names) undergoes HTML entity encoding before being sent to PostGrid to prevent cross-site scripting (XSS) attacks. Special characters like <, >, and & are escaped to their HTML entity equivalents. The frontend also performs client-side validation before submission, and the backend API validates all inputs server-side to ensure data integrity and prevent injection attacks.
File Management: Images are stored with appropriate cache control headers and unique filenames to prevent overwrites and enable efficient CDN caching.
Technical Stack
- Frontend: Next.js 14 (App Router), React, TypeScript
- Backend: Next.js API Routes
- Database & Storage: Supabase (PostgreSQL + Storage)
- Print & Mail API: PostGrid
- Styling: Tailwind CSS with custom typewriter font (Special Elite)
Notes
Gallery: Coming soon! We'll be posting the physical postcards in a gallery for everyone to review once they arrive.
Shipping: All postcards are mailed to my address in St. Charles, MO via PostGrid's mass mailing API. The PostGrid API handles the printing and physical mailing through the USPS.