The Build Journal: Perfecting Preservation

Today, we are officially ready for real-world use. The pipeline is hardened, our sparse data ingestion issues are resolved, and the document analysis engine is producing the most historically authentic narratives we've ever seen.

With the web platform solidified, our focus has shifted to the mobile app experience. We are actively building out the mobile app using Capacitor, wrapping our mainline Vite/React codebase into a native shell to provide a seamless, camera-first scanning interface.

We scaffolded our Xcode and Android Studio projects, integrated the native camera preview plugin for rapid document snapping with direct haptic feedback, and set up our Play Store closed alpha testing tracks to get the app into the hands of real testers. We are finalizing our store listings, setting up Apple’s mandatory Privacy Manifest, and preparing provisioning profiles for App Store submission. The goal is simple: allow families to preserve their physical shoeboxes of letters directly from their kitchen table, using nothing but their phones.

This week we completed a comprehensive "Sparse Input Audit" of the entire document analysis engine. We discovered that our downstream mapping, timeline, and deep research tools were only reading the raw English translations from the database, ignoring nearly 75% of the rich context extracted by the initial AI parser—such as relationship dynamics, environmental settings, and golden quotes. We refactored all core prompts and parser libraries to consume the full data array. Now, our GeoNet maps compile between 30 and 50 nodes per project, up from a sparse baseline of 15.

To lower the barrier for families starting their digitizing journey, we designed and deployed our "First Scan Free" microproduct. New users can snap one document with their phone camera, see the OCR work, and instantly read a personalized Micro-Dossier (complete with an analysis teaser and historical questions) without creating an account.

To protect the system, we built a custom rate-limiting engine utilizing a DynamoDB single-record list pattern, preventing budget-draining API abuse on anonymous uploads while keeping the upload limit at a strict 10MB for free scans. We also upgraded the Face Tagger tool so that user-written descriptions of tagged individuals are fed directly into the Gemini prompt payload, allowing custom family memories to directly shape the final historical summaries.

Some of the worst bugs are the ones that don't crash the server, but silently dilute the user experience. This week, we caught a major routing disconnect: users purchasing premium visual upsells (like the GeoNet Maps and Interactive Timelines) were occasionally receiving blank or sparse diagrams. The pipeline was working perfectly, but a directory mismatch was directing the visualization engines to read from the raw outline directory instead of the rich 4MB text fragment store under heritage/fragments/. We rerouted the ingest pipeline, bringing full detail back to our paid features.

We also tackled the subtle art of translation. When parsing Polish documents, our translation engine literally translated the cultural term "tybetki" (traditional floral wool shawls) to "Tibetan scarves," losing the historical context. We updated the prompt wrappers to inject cultural and localized heuristics when translating Eastern European records.

Finally, we hardened the AI against historical dates. After the model confidently hallucinated a protagonist's birth year based on a random calendar date found in a letter header, we added strict date lockouts to the core system prompts: zero fabrication of names, dates, or places. We also updated our frontend upload interface to completely remove the legacy volume surcharge, aligning it with our updated pricing schema.

We build Theirloom entirely on weekends. Our progress isn't measured in daily sprints, but in late Saturday nights and Sunday mornings. Over the past month of weekends, we realized that preserving history is inherently collaborative. One archive is rarely enough; families wanted copies of the Heritage Dossier for siblings, cousins, and grandchildren. To support this, we operationalized our commerce layer, building a persistent, scalable reprint and gifting pipeline to handle custom print runs and bulk orders, completely automating what used to be days of manual email coordination.

Our Graphic Novel engine hit a critical snag: character consistency. Simple pronouns were causing severe prompt drift in the image generation model. If the text said "he walked in," the model would occasionally swap the grandfather's face with a generic placeholder. We implemented strict Character Lock Injection and pronoun face-tagging directly into the compiler. The result is a visual narrative where faces remain mathematically identical across every single panel.

We also hunted down the invisible bugs. We spent weeks battling "Mojibake"—corrupted characters in our legacy document OCR pipeline—and built an intelligent "Heal" system that automatically repairs broken text encoding. Finally, we completely restructured our front-end deployment pipeline. By forcing our S3 infrastructure to serve raw, extensionless HTML instead of falling back to our Single Page App shell, we solved a massive indexing block. The public examples, historical deep dives, and extraction guides we use to showcase the platform are now fully visible to search engines, bringing our mission to the families who need it.

Our first real customer hit "Purchase" and watched a progress bar sit at zero for eleven minutes. The pipeline was working perfectly — they just couldn't see it. The enrichment phase, where we cross-reference every document against historical context, was writing nothing back to the status table. Eleven minutes of silence.

We injected a progress heartbeat into the enrichment core. Now customers see six distinct updates as their archive moves through the system: preparation, extraction, enrichment, synthesis, export, and delivery. Small fix. Enormous difference.

We also learned a hard lesson about infrastructure drift. For weeks, we'd been patching individual functions directly — a hotfix here, a quick deploy there. Fast, but our production environment was slowly diverging from the source of truth. This week we enforced a strict "clean room" deployment protocol: every change, no matter how small, goes through a full infrastructure synchronization. Forty functions. One atomic deployment. No exceptions. We rebuilt the generative layer around a central registry — when we improve writing quality for one product, every product benefits.

The system we run in production is now, byte for byte, the system we test locally.

We ran the first end-to-end test of the full payment-to-delivery pipeline in production. What we found was humbling: webhook routing was fragile, status updates were inconsistent, and the handoff between payment confirmation and archive generation had three separate race conditions. We rebuilt the commerce layer to be deterministic — every step writes proof to the database before proceeding to the next. No more trust-based handshakes.

We also launched two features that don't sound exciting but change everything for families with messy shoeboxes. An intelligent sorter that examines your uploaded files and arranges them chronologically — not by filename, but by actual content. And a naming system that reads each document and suggests a human-readable label. A customer with 173 photos named "IMG_4392.webp" through "IMG_4565.webp" now sees them organized by decade, with names like "1952 Wedding Reception" and "1978 Lake House Summer."

We updated our legal framework to be explicit about how shared archives are hosted, and synchronized our privacy documentation with our actual technical practices. Transparency isn't a marketing decision — it's an engineering one.

After months of local prototyping, we made our first real commit to cloud infrastructure. One serverless function. One database table. One S3 bucket. Then all eight product types were tested end-to-end: Heritage Dossier, Children's Book, Graphic Novel, Short Story, Biography, Acrostic Poem, Limerick Collection, and Deep Research Report. Every single one had at least one critical failure on the first attempt — broken price IDs, missing headers, a biography generator that confidently wrote about the wrong person. By 4 AM, all eight were passing.

Safari nearly broke us. WebKit was silently converting file uploads into Blob objects, altering HTTP headers and triggering cryptographic signature mismatches. Every iOS user hit a wall of 403 errors. After two days of debugging, we bypassed browser MIME inference entirely with raw byte streams. Aggressive, ugly, and bulletproof.

Then the worst kind of bug: the one that produces output. Our system was silently dropping metadata between the browser and the server. The pipeline would run, the AI would generate, and the customer would receive a beautifully formatted dossier — about nothing. All structure, no substance. The fix required rewriting the handoff between three separate systems.

We launched this journal and our Extraction Guides — step-by-step tutorials for digitizing letters, photos, and documents. The best archive starts with the best source material.

We realized that being a "black box" wasn't enough. To truly honor family history, we must be technically transparent in our values. Today marks the launch of this journal and our commitment to absolute data sovereignty.

We upgraded our core intelligence layer for deeper linguistic nuance, and initiated a global audit to ensure absolute narrative authenticity across all generated content.

A 10-retry loop nightmare almost broke our spirits. WebKit browsers were silently rewriting our upload payloads into Blobs, altering the HTTP headers, and triggering cryptographic signature mismatches. S3 hit us with a wall of 403 Forbidden errors.

After two straight days of debugging, we re-engineered the client to use a raw bytestream parameter, bypassing browser MIME-intercepts entirely. The fix was ugly but effective. We now process massive archival packets without a single 403.

The Digital Explorer is live. We moved the entire system to a Webhook-Triggered Job model, ensuring that your archive is only initialized once the payment intent is fully secured.

This was a necessary step. The system went from a technical prototype to something a paying customer could actually trust with their grandmother's letters.

To keep the writing authentic, we developed a proprietary editorial mechanism. Its primary directive is to eliminate cliché and repetitive phrasing, forcing the narrative to rely strictly on the evidence provided.

We finalized our secure, multi-layered infrastructure to ensure stability and privacy at scale.

The first real breakthrough came after weeks of fighting silent pipeline crashes. The problem was a "Blank Dossier" bug: strict path-stripping logic was accidentally deleting historical context, feeding the compiler flat, empty arrays.

I grabbed my own family letters ("The Andy Compendium," a disorganized mess) and ran them through the system over and over. PowerShell parser errors. Lambda timeouts at the 15-minute wall. Eventually the system stopped mangling the evidence and started reporting it. The output finally read like history, not hallucination.

We spent weeks identifying algorithmic writing tics. We realized that standard text generation leans heavily on abstract, melodramatic metaphors.

We engineered a harder approach. Our standard now is strictly concrete: nouns over metaphors, truth over filler. We write like historians.

Standard OCR was completely failing on 19th-century cursive. I spent three sleepless nights staring at a faded 1924 script, manually tuning bounding boxes just to get the machine to read a single phrase.

That sheer frustration led to a breakthrough: a hybrid pipeline that prioritizes character-by-character resolution for degraded ink. We can now read the letters your great-grandparents wrote with over 99% accuracy.

An early Christmas gift. Tonight, we officially rebranded from "The Alchemist's Press" to Theirloom. The name finally matched what we were actually building: not a novelty press, but a place where family records go to survive.

We connected the revision loop and updated the writing engine's internal labeling system to use historically grounded categories.

This is where the writing engine was born. The first version sounded like a Wikipedia article. The second sounded like a Hallmark card. Neither was acceptable. We needed writing that read like good journalism: specific, grounded, and sourced.

After throwing out a dozen prototypes, we landed on an architecture that keeps the narrative engine completely separate from the user interface. One side handles documents. The other side writes about them. They never touch.