Engineering Development

The news dropped.

OpenAI released gpt-image-1.5 on December 17, 2025:

• 4x faster generation
• 20% cheaper than gpt-image-1
• Better instruction following
• Improved text rendering
• First 5 input images get high fidelity (vs 1 for older models)

The question wasn't "can we support this?" - it was "how fast?"

The answer: 30 minutes.

We'd already done the hard work during the Gemini 3 Pro integration in November. That sprint forced us to refactor from a monolithic single-provider system to a modular multi-provider architecture.

The key insight: All OpenAI image models share the same API surface. gpt-image-1, gpt-image-1-mini, and now gpt-image-1.5 all use the same endpoints, same parameters, same response format.

So when we built OpenAIImageGenerationService, we made it model-agnostic:

// Routes ALL gpt-* models - no specific model checks needed
$postData = [
    'model' => $model,  // Just pass through whatever model is selected
    'prompt' => $prompt,
    // ... same params for all models
];

The implementation was pure configuration:

1. Add to SettingsSchema options
2. Add to FormRequest validation rules
3. Add to pricing config
4. Update frontend model detection

That's it. No service changes. No new classes. No refactoring.

Three challenges converged in December:

1. Prompt Crafting Was Manual and Tedious
Users wrote prompts for image generation, but transforming a casual description into a camera-ready shot description required expertise. "A guy walking in rain" could become something much more evocative with proper cinematographic language - but who has time to learn that?

2. Performance Was Silently Degrading
N+1 queries had crept in across Gallery, Chat, and the Jobs page. Each page load triggered dozens of extra database queries. With growing data volumes, response times were increasing imperceptibly - until they weren't imperceptible anymore.

3. iOS Safari Touch Was Broken
After keyboard dismiss on the Chat page, the entire page became unresponsive to touch. Users had to switch apps and come back just to continue typing. This was WebKit bug #176454 - nested overflow-hidden elements creating touch "dead zones".

The Rephrase System: From Concept to Production in 48 Hours

The idea started simple: what if AI could transform casual prompts into professional shot descriptions? We had the Gemini models, we had the async job architecture from Chat. Why not apply it to prompts?

Day 1: Built the core ProcessRephraseJob following Chat's async pattern - broadcast "thinking" event, call Gemini, broadcast result. Added RephraseAttempt model for tracking status and costs.

Night 1: Realized users needed guidance on how to rephrase. Created SystemPrompt model with admin-configurable presets. The "Scene Clarifier" preset was born - transforming scene descriptions into camera-ready shots.

Day 2: Frontend modals (RephrasePresetModal, RephraseResultModal), image context support (attach 2 images for smarter transformations), and the RephraseAnalytics page. Complete feature shipped.

The N+1 Hunt: Systematic Performance Optimization

Armed with Laravel Debugbar, we profiled every major page:

• Gallery: 47 queries → 8 queries (eager loading relationships)
• Chat: 23 queries → 6 queries (conversation.messages eager load)
• Jobs page: 31 queries → 4 queries (batch loading with with())

The pattern was always the same: iterate over a collection, access a relationship, trigger a query. The fix was always the same: add the relationship to with() in the initial query.

The iOS Safari Fix: Debugging WebKit in Production

The touch bug was maddening. It only happened after keyboard dismiss. It only happened in Safari. It only happened with our specific DOM structure.

The culprit: nested overflow-hidden elements. WebKit bug #176454 causes touch events to stop propagating through certain overflow configurations. The fix required three changes:

1. GPU layer forcing with translateZ(0) to trigger repaint
2. touch-action: pan-y for explicit touch handling
3. Momentum scrolling via -webkit-overflow-scrolling: touch

We also fixed pull-to-refresh incorrectly triggering on Chat and added the AppLayout provide/inject pattern for explicit PTR disable on specific pages.

The server was dying. 500 errors everywhere. Redis screaming:

MISCONF Redis is configured to save RDB snapshots, but it's currently unable to persist to disk

The diagnosis:

• Disk at 93% full (only 2.6GB free on 38GB)
• Redis consuming 4.49GB of memory
• 79,609 MISCONF errors logged in one day
• gemini:chat:* keys = 4.3GB (96% of Redis!)

The root cause? Model-generated images with "thought signatures" were being stored as full base64 in Redis. Each conversation could be 60-100MB. With 485 conversations, Redis was bloated beyond capacity.

Here's where it gets interesting.

This entire debugging session happened via iPhone SSH. David was on the Copenhagen Metro, heading to work, using Termius to SSH into the production server. Claude Code was running directly on the server instance.

The YOLO preface: This approach is explicitly NOT recommended for production applications with external users. But for a hobby project with automated Hetzner backups? YOLO. For rapid prototyping, there's no equivalent to fixing issues on the spot.

The investigation unfolded:

First, immediate triage - freed disk space by removing Redis temp files (2.8GB), old logs, and Docker images. Disk dropped from 93% to 86%.

Then the deep dive. We found that FileReferenceService.ts was deliberately skipping model-generated images:

if (part.thoughtSignature || part.thought) {
  console.log('[FILE_REF] Keeping model-generated image as base64...');
  continue;  // THIS KEEPS 1-10MB PER IMAGE IN REDIS
}

But why? The Gemini SDK strips thoughtSignature from fileData parts during serialization. This field is critical for multi-turn conversations - without it, Gemini returns 400 errors. So these images HAD to stay as inlineData (base64).

The insight: We can't use Gemini's File API for thought-signed images, but we CAN store the image binary locally and keep only a reference in Redis. Same pattern as the File API fix, but for a different constraint.

A chat message failed on production. The curl response was unusual - empty reply from server.

Investigating the logs revealed the truth:

FATAL ERROR: Reached heap limit Allocation failed
- JavaScript heap out of memory

The Express Gemini microservice had crashed. Not a network blip. Not a Gemini API issue. Out of memory.

Digging deeper into the container logs showed the crash happened while processing conversation 225 - a conversation with 21 images. The heap was at 1.9GB when it died.

The architecture flaw was clear once we saw it:

Every message, the rehydrateHistory() function loaded ALL images from Redis into memory as base64. 21 images × ~100KB × 3-4 deep clones during processing = 2GB+ heap.

The container auto-restarted and the retry worked, but this was a ticking time bomb. Any conversation with enough images would crash the server.

"How do other services handle this?"

That question changed everything. ChatGPT, Claude, every major AI service handles image-heavy conversations - they don't load everything into memory every time.

The answer: cloud storage + URLs. Upload files to a service, pass just the URI to the model. The model fetches what it needs.

Then we discovered Gemini File API.

Google provides a free File API where you can upload images and reference them by URI. The Gemini SDK accepts these URIs directly - no need to load base64 into memory at all. Files expire after 48 hours, but we could keep local backups and re-upload on demand.

Here's where it gets interesting.

I wrote a comprehensive implementation plan with phases, error handling strategies, monitoring endpoints, and testing criteria. At the bottom:

8-10 hours estimated.

But we didn't need 8-10 hours. We had context. We understood the problem. We knew exactly what needed to change.

The implementation took 15 minutes.

Two new service files. Updates to the ChatManager. Debug endpoints. The entire architecture shift - from "load everything into memory" to "pass URIs to Gemini" - done in a single focused session.

Running npm run type-check produced a wall of red. 200+ TypeScript errors across the Vue 3 codebase.

The errors weren't random - they clustered around specific patterns:

• AcceptableValue unions - shadcn-vue's Select components emit values that include bigint, but our handlers only accepted string | number. Every dropdown was a potential type mismatch.

• Readonly array friction - Pinia stores return readonly() arrays for immutability, but child components expected mutable arrays. Props that should "just work" threw type errors.

• Template ref typing - Vue 3's template refs and MaybeRef utility types weren't playing nice with our composables. The useRowAwareExpansion hook couldn't accept refs from parent components.

• Interface drift - Local component interfaces like Image had diverged from the canonical galleryStore.Image. Properties were missing, types didn't match, and every file had its own slightly-wrong definition.

• Third-party type gaps - Splide.js and Swiper.js lacked complete TypeScript definitions. We were flying blind on carousel components.

The codebase worked at runtime, but the type system couldn't prove it.

The approach: systematic, not scattered.

Rather than playing whack-a-mole with individual errors, we identified the root patterns and fixed them at the source.

AcceptableValue handlers came first.

shadcn-vue's Select component emits an AcceptableValue type: string | number | bigint | boolean | Record<string, unknown> | null. Our handlers only accepted partial unions. The fix was simple once identified - extend every handler to accept the full union, then coerce to the expected type:

function handleChange(value: AcceptableValue) {
  emit('update:value', String(value));
}

Applied across GalleryFilterSheet, GalleryPickerModal, ProjectScenePanelSelector, CostDashboard, AnalyticsFilters, and more.

Readonly arrays needed prop flexibility.

When useCostAnalytics returns readonly(trends), passing to <CostTrendChart :trends="trends" /> fails if the prop expects CostTrend[]. The solution: accept both:

interface Props {
  trends: readonly CostTrend[] | CostTrend[];
}

Applied to CostTrendChart, ModelBreakdownChart, and CostSummaryCards.

Template refs required permissive typing.

useRowAwareExpansion expected Ref<HTMLElement | null>, but parent components passed various ref types. The fix uses Vue's MaybeRef with an escape hatch for complex template refs:

export function useRowAwareExpansion(
  gridRef: Ref<HTMLElement | null> | MaybeRef<any>,
  itemCount: MaybeRef<number>
)

Interface consolidation was the big win.

ImageDetailsSheet.vue had its own 40-line Image interface that was missing metadata, inpaint_attempt_id, and parent_image. Instead of keeping it in sync, we deleted it entirely and imported from galleryStore:

import type { Image } from '@/stores/galleryStore';

Then we enriched galleryStore.Image with the missing properties so all consumers benefit.

Third-party types got declaration files.

For Splide.js, we created resources/js/types/splide.d.ts with comprehensive SplideOptions and SplideInstance interfaces. Same for Swiper - making SwiperContainer extend HTMLElement so classList access works.

Edge cases got individual attention:

• KonvaCanvas.vue - Removed .value from template (Vue auto-unwraps refs)
• Settings.vue - Type assertion for dynamic prompt_templates.${index} error keys
• Profile/Edit.vue - Added status and is_admin to User interface
• Inpaint/Create.vue - Fixed typo: props.imageSizes → props.gptModelSizes
• Gallery/Index.vue - Nested panel structure in assignment callback

Ever tried to refine an AI-generated image?

"Make the sky more dramatic." "Actually, less dramatic." "Can you keep the clouds but change the colors?"

With single-shot generation, you'd start from scratch every time. No memory. No context. No conversation. Just generate → view → repeat.

We wanted something better.

It started simple.

We built an Express microservice to talk to Gemini. Send a message, get a response. Basic chat worked on day one.

Then reality hit.

Gemini takes 5-10 seconds to think. A frozen UI? Unacceptable. So we rebuilt everything around jobs and WebSockets. Now you see a "thinking" animation while Gemini works, and responses stream in the moment they're ready. Night and day difference.

Then users asked the hard question.

"What if I want to edit my earlier message?"

Here's the problem: Gemini maintains "thought signatures" - internal reasoning state that becomes invalid if you change history. You can't just edit in place.

Our solution? Forking. Click edit, and we branch the conversation. Your original stays intact. The fork picks up from that point with your new message. Git for conversations, basically.

Then we hit a wall.

A 10-message chat with images was eating 6MB of Redis. Per conversation. That doesn't scale.

The fix: dehydration. We pull large blobs (images, thought data) out to disk and leave lightweight references in Redis. Same instant load times, 92% less memory. Now conversations can live forever.

Then came the polish. Lots of it.

Model selection arrived next - Gemini 2.5 Flash for quick iterations, Gemini 3 Pro for quality and 4K resolution. Then response modes: text-only, image-only, or let the AI decide.

Resolution and aspect ratio controls followed. Users wanted control over output dimensions without leaving the conversation.

Mobile testing revealed a problem: accidental sends. Tapping Enter on a phone keyboard would fire off half-finished messages. Solution: require Cmd/Ctrl+Enter on desktop, use the send button on mobile.

The AI personality layer.

System instructions let you configure how Gemini behaves. "Be concise." "Focus on comic book art." "Always suggest alternatives." Each conversation can have its own personality.

Default settings came next - your preferred model, resolution, and response mode saved so every new conversation starts the way you like.

We added reasoning display too. When Gemini shows its thought process, you can expand it and see how it arrived at its answer.

Conversation management improvements.

Conversation previews in the sidebar - see the first message and response without opening each one.

Prompt templates: 5 reusable text snippets you define in settings, accessible from a quick menu. Perfect for repetitive instructions.

And the infrastructure work.

Cost tracking integration - every chat message calculates tokens and cost, rolling into your monthly analytics.

Docker containerization for the Express microservice. CI/CD pipeline for deployments.

Better error handling, upstream failure recovery, job lifecycle feedback improvements.

31 commits. Each one solving a real problem we hit while using it.

The original PanelForge architecture tied images directly to panels through a rigid one-to-one relationship. Every image HAD to belong to a specific panel within a specific scene within a specific project. But comic creation workflows are messy - artists often have reference images that apply to an entire project, scene sketches that aren't panel-specific yet, or generated images that could fit multiple contexts. The rigid structure forced artificial organization decisions. Additionally, navigating large image collections required extensive scrolling with no visual hierarchy representation.

This feature evolved through two distinct phases over an intensive development session. Phase 1 (fa6f955) tackled the database schema - adding project_id and scene_id to images with SQLite-compatible migrations and Eloquent auto-sync events, plus the ProjectScenePanelSelector cascading dropdown component. Phase 2 (b64fe6c+) introduced tree navigation, initially as a dedicated Browse page, but user testing revealed context-switching friction. The QA process led to merging everything back into a unified Gallery with tree navigation embedded - eliminating 2,200+ lines through consolidation while improving the experience. The comic book Panel Forge branding emerged organically during Phase 2, with Bangers and Comic Neue fonts giving the tree a distinctive visual identity. What made this collaboration powerful was the willingness to iterate - recognizing that the "right" architecture emerged through exploration, not upfront planning.