"Why pay $3/month for Google One when you can spend 3 weeks building a private photo gallery instead?"

It started with Google Photos.

Specifically, it started with Google Photos deciding that my perfectly functional 2016 Pixel — a phone Google themselves promised unlimited original-quality storage to forever — no longer deserved unlimited original-quality storage. Forever, apparently, was a marketing term.

Fifteen gigabytes. Shared with Gmail. For a family photo archive.

Fine. I'll build my own.

The Architecture That Got Out of Hand

Here is the pitch: old Pixel devices already have Google Photos running locally. Google Photos backs up whatever it finds in a watched folder. So the plan was to run the backend on the Pixel itself, dump uploads into a sync folder, let Google Photos do the backup, then purge the originals after 12 hours. Previews stay forever. Gallery reads from Firestore metadata and preview files.

Reader, I drew a flowchart. It had six boxes. By the time I shipped, it had 14.

The actual pipeline:

1. Flutter app authenticates via Firebase OAuth
2. Upload goes to the Fastify API using the tus protocol — resumable uploads, because uploads die midway and life is pain
3. A BullMQ job fires off the upload worker
4. Worker moves the original to /sdcard/ShashinMori/<uid>/... (Google Photos picks it up automatically)
5. Worker runs Jimp to generate an optimized preview
6. Worker writes metadata to Firestore
7. A 12-hour cleanup job purges the original from the sync folder after backup
8. Gallery endpoints serve from Firestore metadata + the retained preview

This is what "simple photo backup app" looks like at 2 AM.

The Tech Stack, Annotated

Flutter + Riverpod + GoRouter on the frontend. Riverpod is the state management solution that makes you feel vaguely competent until BuildContext eats your soul. GoRouter is fine. Dart is fine. Writing Dart is like TypeScript with training wheels, which is either reassuring or insulting depending on your perspective.

Fastify + TypeScript on the backend. Faster than Express, more opinionated than I expected, very happy with it once the plugin system clicked.

tus protocol for uploads. The resumable upload standard that nobody talks about until you're dealing with spotty mobile connections and 50MB RAW files. @tus/server handles the chunked upload dance. The client-side tus_client_dart package does the same on Flutter. When it works, it's magic. Getting there was not magic.

BullMQ + Upstash Redis for the job queue. Fire and forget. The worker processes asynchronously so the upload endpoint returns fast and the heavy Jimp processing doesn't block anything.

Jimp for image processing. Pure JavaScript, no native binaries, runs on the Pixel without drama. Slower than Sharp. Doesn't require compiling native modules on ARM. Trade-offs.

The Design Decisions I Will Defend

This is an append-only archive. No delete. No download. Intentionally.

The point is preservation, not management. Photos go in. They stay in. Google Photos has a copy. The preview is always there. Nothing accidentally disappears because someone's toddler tapped delete.

Multi-user isolation is enforced at the Firestore level — every record is scoped to a UID, so family members sharing the backend can't see each other's photos.

Is it overkill for a family gallery? Absolutely. Is every architectural decision technically justified? Yes, actually. That's the worst kind of overkill.

What I Actually Learned

File uploads are a protocol, not a feature. If you're doing anything beyond a single-chunk POST, just use tus from the start.

BullMQ with Redis makes async job queues embarrassingly easy. The worker model — receive upload, enqueue job, return 200, process later — is the correct mental model for anything involving I/O you don't control.

Running a backend on a Pixel device is completely viable and deeply unhinged. Termux + PM2 + Docker-compatible deployment targets. I have regrets about the path I took to learn this.

The Numbers

• 6 npm packages that actually matter, surrounded by 30 that exist
• 1 old Pixel phone running a production API server in my living room
• 0 delete endpoints, on purpose
• 12 hours before originals get purged from the sync folder
• Indefinite preview retention, because that's the whole point

ShashinMori is open source. The architecture diagram alone is worth cloning it.

Grab it on GitHub. Your old Pixel deserves a second life.

Normal people: pays $20/month for hobby project hosting. Me: roots phone, installs Termux, rewrites deployment infrastructure from scratch at midnight.

Both are valid approaches to the problem. I'm not here to judge. I'm here to explain the sequence of decisions that led to me configuring Nginx on a Snapdragon 660 while the phone was also playing a lo-fi playlist.

The Inciting Incident

I had a rooted Android phone sitting in a drawer. I wanted to host some side projects. Vercel exists. Railway exists. Render exists.

I chose the drawer phone.

What Is MiniShinobi

It's a self-hosted, Vercel-like deployment platform that runs entirely inside Termux on a rooted Android device. You connect a GitHub repo, hit Deploy, and your project goes live on a real subdomain over HTTPS via Cloudflare Tunnel — all from a device that charges next to your bed at night.

The stack: Node.js backend, Vite/React dashboard, Nginx reverse proxy, PM2 for process management, sql.js for the database, and cloudflared for tunnels. All of it supervised by PM2 on a phone.

"We'll Just Use sql.js"

The first design constraint: you cannot compile better-sqlite3 on ARM Termux. Native Node addon compilation on ARM is a special kind of unpleasant that I don't recommend.

So the database runs on sql.js — SQLite compiled to WebAssembly. Zero native compilation, zero segfaults. Every write flushes the entire database buffer to disk. The database is small. The phone has 4 GB of RAM. This is fine.

It's cursed in a way that is technically completely fine.

"We'll Just Use child_process"

Similarly, node-pty needs native compilation. You know how that story ends.

So the entire deployment engine — git clone, npm install, npm run build, framework detection, process spawn — runs through Node's built-in child_process.spawn. Every byte of stdout and stderr is line-buffered and streamed live to the browser via Server-Sent Events. You watch your build happen in real-time from the dashboard, which is serving you that stream from a phone in your drawer.

Does it feel like it should work? No. Does it work? The phone is serving things to the open internet right now.

"We'll Just Use PM2"

pm2 start ecosystem.config.js and everything wakes up: the Express backend, Nginx, and cloudflared. Three supervised processes, one config file. If anything crashes, PM2 restarts it. On a phone.

This is the part where I discovered PM2 is genuinely great and I should have been using it everywhere.

The Build Queue (The Unsexy Correct Decision)

4 GB of RAM sounds fine until npm run build on a React app invites the OOM killer to the party.

There's a serialized build queue. One build at a time. If you deploy two projects simultaneously, one waits. It's not exciting. It's the right call for a device with less RAM than most laptops have VRAM.

I also added 1 GB of swap. Don't look at me like that.

Cloudflare Tunnels Are Legitimately Magic

cloudflared is the part that makes all of this actually work. You run one daemon, write a YAML config, and localhost:3000 is suddenly reachable at your-project.yourdomain.com over HTTPS with a valid certificate.

No port forwarding. No public IP. No router config. No DynDNS prayers. Every deployment gets its own named tunnel. Every project gets its own subdomain. The phone sitting in a drawer is serving real traffic on the real internet.

Does It Actually Work?

Build logs stream live. Deployments go live. GitHub OAuth works. Static sites and Node apps both deploy. The framework detector auto-detects Next.js, Vite, and plain static sites. SSL certificates are valid.

Running on a Snapdragon 660, 4 GB RAM, PixelExperience Android 13. The phone is also charging. The lo-fi playlist is still going.

Did I need to build this? No. Do I have a full deployment dashboard running on a rooted Android phone for exactly $0/month? Yes.

That's just engineering.

MiniShinobi is open source. If you have a rooted Android phone gathering dust and a questionable relationship with free time, the README has every command. I already did the part where you discover why you shouldn't do this. You get to skip straight to the part where it works.

"Throughout the filesystem and the disk, I alone am the honored one."

It started, as all terrible ideas do, with a minor inconvenience.

I ran npkill on my projects folder -- five years of side projects, abandoned tutorials, and repos I swore I'd finish. It found 50,000+ directories. Twelve seconds just to scan. Sequential size calculation. And when I hit delete on a 5GB node_modules? The UI froze while Node.js heroically attempted thousands of blocking I/O calls.

Unacceptable.

So naturally, I chose the hardest possible approach.

The Architecture Nobody Asked For

I call it hakai (破壊) -- "destruction" in Japanese -- because naming things is the second hardest problem in computer science, and for once, this one was easy.

The core insight: JavaScript is not built for high-performance filesystem work. Rust is. So the engine -- scanning, size calculation, deletion, risk analysis -- is compiled Rust. rayon gives me a work-stealing thread pool that distributes directory traversal across every CPU core. It's embarrassingly parallel and I'm not embarrassed at all.

But here's where the yak-shaving gets beautiful.

Building TUIs in Rust is... an experience. So the frontend -- keybinds, diff-based rendering, regex search, multi-select -- runs in Bun. Sub-50ms startup, 60fps rendering, and I already knew TypeScript.

The two halves talk over a newline-delimited JSON IPC protocol on stdin/stdout pipes. Rust fires scan results, sizes, and deletion progress down stdout. Bun catches it on stdin, parses each line, renders without blocking. One JSON object per line, trivially debuggable with jq.

A chaotic marriage that infuriates purists on both sides. Perfect.

The Benchmarks of Spite

Here's what happens when you massively over-engineer a file deletion tool:

When you multi-select 100 folders and hit enter, hakai fires up to 8 concurrent deletion tasks via tokio. The UI never blocks. The scan never pauses. Folders just vanish. It finishes before your hand reaches the mouse.

The Weekend That Kept Growing

Let me be transparent about the scope creep.

What started as "make npkill but faster" turned into: cross-platform path handling for Windows' 260-character MAX_PATH limit (solved with \\?\ UNC prefixes). Fixing TTY detection for Windows Git Bash, which is somehow still broken in 2026. Adding risk analysis that flags orphaned node_modules missing a package.json so you don't nuke a monorepo root. Building a headless mode with --json output for CI pipelines because scope creep doesn't stop until the PR is merged.

"It works on my machine" wasn't good enough. It had to work on everyone's machine.

Was It Worth It?

I spent a full weekend configuring Rust cross-compilation targets, debugging IPC buffer edge cases, and fighting tokio task cancellation semantics -- all to save roughly 10 seconds of my day once a month.

Let's do the math. If I use hakai twice a month and save 12 seconds each time, I'll break even on development time in approximately... 47 years.

But that benchmark table looks really good in a README.

So yes. Obviously worth it.

Grab hakai on GitHub. Your node_modules had it coming.

Windows built-in disk cleanup: freed 2MB. My hidden AppData caches: 40GB. The math here is upsetting.

My C: drive bar turned red.

You know the one. That international symbol for "everything is about to break and it is entirely your fault." Standard protocol: download a third-party cleaner. So I went looking.

Option A: "free" cleaners bundled with three toolbars that want to be my default browser and cap you at 500MB of deletion before demanding a $40 annual subscription.

Option B: Actually pay $40 a year for something the OS should natively do, wrapped in an interface that looks like a 2004 Vegas slot machine.

I looked at macOS. CleanMyMac. DaisyDisk. Beautiful, fast, honest about what they're deleting.

I looked back at my red C: drive bar.

"Fine. I'll do it myself."

The WiMo Architecture: PowerShell Does the Work, Go Makes It Look Good

Windows PowerShell is basically the native language of the Windows API. It can touch the registry, query WMI, talk to Winget, manage services. It's deeply powerful and its TUI capabilities are, charitably, equivalent to arranging rocks in mud.

Go, with the Bubble Tea and Lip Gloss frameworks, renders genuinely slick real-time terminal UIs.

So: PowerShell handles the heavy lifting. Compiled Go binaries handle the visuals. The two halves cooperate.

The command surface:

28+ cleanup targets across user caches, browser data, package managers, and dev tool leftovers.

The 4-Layer Safe Delete System

I gave this thing admin rights. That is not a decision to make lightly.

Every deletion goes through four checks before anything touches disk:

1. Protected path check — C:\Windows, C:\Program Files, and other system-critical directories are hardcoded off-limits
2. User data pattern check — Documents, Desktop, Downloads, Pictures are always preserved
3. Recycle bin fallback — files go to Recycle Bin when possible, not permanent deletion
4. Dry-run preview — wimo clean --dry-run shows exactly what would be removed before committing

You can run it with admin rights and not lose your Documents folder. That felt important to test thoroughly.

The Purge Command: Born of Pure Developer Spite

wimo purge was written specifically because I discovered my D: drive had 15GB of node_modules from projects I haven't touched since 2023. Plus Rust target directories. Plus Python __pycache__ scattered across everything.

PowerShell runspace pools run up to 16 concurrent threads for size calculation and deletion. System.IO.Directory.EnumerateFiles() replaces Get-ChildItem -Recurse for scanning that is actually fast. It finds the artifacts, calculates their sizes in parallel, and removes them concurrently.

The --paths and --depth flags let you scope it. wimo purge --paths "C:\Projects" --depth 5 stays in your lane.

The Go TUI: Because Staring at Plain Output Is Suffering

wimo analyze hands off to a compiled Go binary that renders a live-updating directory tree as it scans. Alt-screen mode. Goroutine-per-directory concurrency. The sizes appear in real time as the scan progresses.

wimo status renders a 6-card dashboard — CPU, Memory, Disk, Network, Processes, System — with a health score badge, a Catppuccin-inspired sage green palette, and 2-second auto-refresh via gopsutil. Responsive layout: stacks to a single column below 70 terminal columns.

These are optional binaries. If you haven't built them, the PowerShell wrapper tells you the build command. It doesn't just fail silently.

The Admin-Awareness Detail I'm Proud Of

WiMo badges admin-required tasks in the UI. If you're running as a standard user, it skips those tasks gracefully and tells you why. It doesn't crash, doesn't silently fail, doesn't demand elevation and then complain.

That's not a flashy feature. It's just correct behavior that most tools in this space don't bother with.

Did I Need To Build This?

Could I have right-clicked and deleted the folders manually? Yes.

Could I have bought a larger SSD for cheaper than the time this took? Probably.

But now I have a tool that doesn't try to install a search toolbar, doesn't cap deletion behind a paywall, and actually tells me what it's about to do before it does it.

I consider that a win. Check out Winmole on GitHub. Your C: drive bar doesn't have to be red.

My right hand is 4cm from the back button. I built an entire Chrome extension instead of moving it.

It started with a reasonable thought.

"I wish I could just swipe to go back."

That's it. No technical problem. No user pain. Just a fleeting preference about mouse navigation that a normal person would think once and immediately forget. I, instead, spent a weekend building a gesture recognition engine, a canvas-based trail renderer, a Manifest V3 service worker, and a full design system for a 400px popup.

The back button is still 4cm away. I've just stopped using it.

Manifest V3: Google's Gift to Extension Developers Who Thought Life Was Too Easy

You know what Manifest V3 took away? The ability to run persistent background pages. Fine, that's a service worker now. You know what else it took? Inline scripts in the popup HTML, because Content Security Policy says no.

That second one meant I needed a build step that extracts inline scripts into separate files at compile time. Not a workaround. That's just the job now. I wrote a custom extract-inline.ts script — 74 lines — that exists entirely because Chrome's CSP decided my popup was suspicious.

I'm fine. The script is fine. We're all fine.

"I'll Just Write a Quick Content Script"

Famous last words.

The content script injects into every page on the internet. It listens for right-click drag events. It detects direction. It sends a message to the background service worker. Done.

What actually ended up in the content script:

A canvas element gets injected into every page. High-DPI support, because gesture trails on a retina display need to be crisp. Quadratic curve smoothing so the trail looks fluid instead of jagged. Real-time cardinal direction labels rendered mid-gesture with arrow symbols. A gesture.ts module with direction detection via accumulated angle deltas.

For going back. And forward. And switching tabs. And scrolling to the top.

The Circle Gesture Problem

I need to talk about circle detection for a moment.

The naive approach: did the mouse path close on itself? Easy. Done. Ship it.

What I actually implemented: accumulated signed angle changes using atan2 cross-products across consecutive path points, checked whether the total exceeds 300 degrees of arc, verified path closure within 80 pixels of the starting point.

This is for refreshing the page. The keyboard shortcut is F5. It has been F5 for thirty years. My circle detection algorithm is more sophisticated than my first three jobs combined.

I have no regrets.

The Gesture Map

Seven gestures. Seven actions.

All triggered by right-click drag. No accidental fires on normal right-click. The direction detection only commits once you've moved enough to make intent clear.

The Build Pipeline That Grew a Pipeline

It's a Chrome extension. You write JS, load it unpacked, test it. Simple.

My build pipeline:

1. Astro compiles the popup
2. Bun bundles the content and background scripts
3. Custom CSP extraction script extracts inline scripts
4. Sharp generates four icon sizes from source
5. Pack script ZIPs everything for distribution

Five tools. For seven features. I wrote more build infrastructure than I wrote browser logic. That's my brand.

The Popup Design System

The popup is 400px wide. It shows a gesture reference table. It will never need server-side rendering. It has no dynamic data whatsoever.

I gave it a full design system. Custom CSS variables. A sage-green palette with named tokens like sage-300 and sage-600. Named shadow tokens. A cubic-bezier easing curve. In Astro.

--shadow-soft: 0 4px 16px rgba(46, 47, 44, 0.04);

--shadow-soft: 0 4px 16px rgba(46, 47, 44, 0.04);

For a popup.

Does It Actually Work?

Yes. Surprisingly well.

The gesture trail is smooth. The direction detection is accurate. Switching tabs with a two-direction swipe is genuinely faster than Ctrl+Tab once you've muscle-memorized it. The circle-to-refresh has completely replaced F5 in my daily workflow.

I created a problem, solved it more thoroughly than necessary, and now can't imagine browsing without it. Standard engineering outcome.

TabiNeko is open source. You can use the back button instead. Both are valid. I won't judge you. I'm too busy drawing circles on web pages to have opinions about other people's navigation choices.

Grab it on GitHub.

"It's broken." — an actual Jira ticket, assigned to you, with no further context, a screenshot of the wrong screen, and the energy of someone who has never once thought about what a developer needs to fix a bug.

Bug reporting in 2026. Still a game of telephone. Still completely broken.

We're in a timeline where AI writes production code, but the standard bug report is still a screenshot cropped to a vague red box, pasted into Slack, followed by four words and the silent prayer that you're also a psychic. By the time that reaches an AI coding agent, the context has fully decayed. The agent writes the wrong fix. You spend 20 minutes explaining what was actually broken. Classic.

AI Feedbacks exists specifically because I got tired of receiving "it doesn't work" as actionable development context.

The Problem Has a Name: Context Decay

When a bug fires on the client side, useful information exists for exactly a few seconds: the DOM state at the moment of failure, the console errors, the failed network requests, the exact UI configuration. Then the user closes the tab, writes "the button did something weird," and submits.

By the time that reaches Cursor or Windsurf, the prompt is so thin it's basically a riddle. Agents hallucinate. Developers reconstruct the crash scene manually before they can even ask the agent to start fixing it.

The technical term is "context decay." The honest term is "why does this happen every single sprint."

The Fix: Capture Everything at the Moment It Exists

The Chrome Extension runs silently in the background. When the user crops and submits a bug report, it automatically:

• Grabs the exact area of the screen they flagged
• Captures every console.error and console.warn from the session (yes, including the ones you've been ignoring)
• Packages all failed network requests (4xx/5xx) from the last 60 seconds
• Captures the DOM state at the time of failure
• Sends the whole bundle to the backend — without the user doing anything else

The developer doesn't receive a blurry screenshot. They receive a structured, agent-ready prompt.

Google Gemini Does the Heavy Lifting

The backend is built with Next.js 15 and powered by Google Gemini 3 Flash Preview for multimodal analysis. Gemini sees the screenshot, reads the error logs, cross-references the network failures, and synthesizes everything into a prompt that actually gives your coding agent something to work with on the first pass.

const result = streamText({
  model: google('gemini-3-flash-preview'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: `Analyze this bug: ${description}` },
        { type: 'image', image: screenshotBuffer },
      ],
    },
  ],
})

const result = streamText({
  model: google('gemini-3-flash-preview'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: `Analyze this bug: ${description}` },
        { type: 'image', image: screenshotBuffer },
      ],
    },
  ],
})

Feed it a screenshot and a vague description. Get back a prompt that Cursor can actually use. Wild concept.

The Dashboard: Because You'll Forget About Last Tuesday's Bug

The web dashboard has natural language semantic search because nobody remembers the exact tag they used two weeks ago.

Search for:

• "that auth error"
• "the white flash on mobile"
• "whatever was broken with the chart last week"

It just finds it. Not because you tagged correctly in a 14-step triage process. Because you described it like a human.

The UI is monochrome, high-contrast, deliberately no-frills. No decorative gradients competing for attention while you're just trying to ship a fix. The #87ae73 accent color is the most exciting thing in the design system, and that's intentional.

Who This Is For

If you use Cursor, Windsurf, GitHub Copilot, or any agentic coding tool — you already know the dirty secret: output quality is 100% constrained by prompt quality. AI Feedbacks automates the hardest part of a good bug prompt: capturing and structuring all the context at the exact moment it exists, before the user closes the tab and forgets everything.

Better context in. First-pass fixes out. Feed your agents better.

github.com/Mic-360/ai-feedbacks

Narrator: The bots were already scanning it.

Hot take: the same sqlmap script hammering Fortune 500 APIs is also currently probing your portfolio project with 50 daily active users. The bots do not care that you're "just a hobby project." They are not reading your README.

The WAF market's solution for this is extremely helpful: $200/month for Cloudflare WAF, or AWS WAF where you pay per rule, per request, and probably per time you think about security. ModSecurity is technically free if you enjoy reading 300 pages of Apache documentation at midnight.

Nobody built a WAF for the person who just wants their side project to stop getting SQL-injected.

So I did.

Introducing Mamoru-WAF

Single Go binary. Zero external dependencies. No Redis cluster. No Postgres spanning three Availability Zones just to store block logs. Just:

go build -o mamoru ./cmd/server
./mamoru --tui

go build -o mamoru ./cmd/server
./mamoru --tui

You're protected. That's the whole pitch.

The Part Where It Does Real Security

Mamoru covers the OWASP Top 10 staples that are most likely to ruin your week:

Regex pattern matching catches SQLi (union, select, drop, sleep), XSS (<script>, onerror=), and path traversal (../) before the request reaches your backend. Your backend doesn't even know it happened.

Token-bucket rate limiting runs per-IP, per-path, configurable. That /api/login endpoint you never hardened? It now has a bouncer.

Request body inspection means your contact form also can't be an attack vector anymore. Yes, POST bodies are checked too.

The rule engine uses a dead-simple Go interface: Name() and Evaluate(). Two methods. You can write a custom rule in 5 lines of Go. Try doing that in AWS WAF without a certification.

Hot Reload: Because Downtime Is For Enterprises

The AtomicEngine handles live rule reloading. Edit rules.yaml, save it, and the new rules are live in 2 seconds — no restarts, no dropped connections, no maintenance windows.

You can toggle between BLOCK mode (hard blocks) and DETECT mode (logs only, nothing blocked) with a keypress. Useful for when you want to watch what's happening before you commit to blocking it.

The TUI Nobody Asked For

I built a Catppuccin sage-green terminal dashboard because WAF logs are otherwise a wall of unreadable JSON and I couldn't live with that.

🛡 MAMORU-WAF                     Mode: BLOCK  │  Backend: ● UP
 Total: 1250    Blocked: 23    Rate: 2    Detected: 0
─────────────────────────────────────────────────────────────────
 Live Events
  12:30:01 [OK]    192.168.1.5  GET    /
  12:30:03 [BLOCK] 10.0.0.50    POST   /login  pattern_filter:pattern_match
  12:30:05 [RATE]  10.0.0.50    GET    /api    rate_limiter:rate_limit
─────────────────────────────────────────────────────────────────
 q quit  │  r reload  │  m mode  │  c clear  │  h help

🛡 MAMORU-WAF                     Mode: BLOCK  │  Backend: ● UP
 Total: 1250    Blocked: 23    Rate: 2    Detected: 0
─────────────────────────────────────────────────────────────────
 Live Events
  12:30:01 [OK]    192.168.1.5  GET    /
  12:30:03 [BLOCK] 10.0.0.50    POST   /login  pattern_filter:pattern_match
  12:30:05 [RATE]  10.0.0.50    GET    /api    rate_limiter:rate_limit
─────────────────────────────────────────────────────────────────
 q quit  │  r reload  │  m mode  │  c clear  │  h help

Built with Bubble Tea. Real-time event log. Backend health panel. Interactive hotkeys. r reloads rules live. d toggles detect mode. q when you've seen enough and need to go to bed.

Nobody asked for a WAF with a terminal dashboard this nice. I built it anyway. It slaps.

The Honest Assessment

Your side project is getting bot-scanned. "I don't have anything worth stealing" is not a threat model. Neither is "I'll add security later."

Mamoru is a 15MB Docker image, a YAML file you can read while half-asleep, and a Go binary that takes 60 seconds to get running.

go build -o mamoru ./cmd/server

go build -o mamoru ./cmd/server

That's it. Mamoru-kun is now watching your traffic so you don't have to.

GitHub — the CONTRIBUTING.md has a guide. The rule interface is two methods. There is no valid excuse.

Spotify: twenty years of existence, billions in revenue, zero A-B loop implementations. I handled it.

Let me tell you what Spotify gives you.

Play. Pause. Skip. Shuffle (broken in a new way every year). Repeat song — meaning the entire track, including the 90-second spoken intro you hate. A seek bar that is functionally useless at precise scrubbing speeds. That's it. That is the complete feature set for a company worth $50 billion.

No loop region. No segment markers. No "skip this intro automatically every single time forever" feature.

It's while (position >= end) { seek(start); }. A junior dev could ship this on a Tuesday. They haven't shipped it in twenty years.

So: Pulse Loop.

What It Actually Does

Two modes. Online and offline.

Online mode connects to your Spotify account via OAuth 2.0. You browse your top tracks, recently played, or search. You set a millisecond-accurate start point and end point. You toggle loop on. The app monitors playback position and seeks back to start the moment it hits your end marker. Sub-120ms seek latency via spotify_sdk. The loop is seamless.

Three playback modes:

• Normal — loops the full track
• Loop — repeats your selected start-to-end segment continuously
• Skip — skips your selected segment and keeps playing the rest

That last one is the feature I didn't know I needed. Set it on every song with a terrible bridge. Gone forever.

Offline mode doesn't need Spotify at all. Upload local audio files — MP3, WAV, M4A, OGG, FLAC, AAC — and get the same loop controls powered by just_audio. Files persist to app cache on Android and IndexedDB on web, so they survive restarts. Automatic metadata extraction from Artist - Title filename format. Full offline, full loop, no account required.

The Tech, Because It Matters

Flutter + Riverpod with code generation. Riverpod's @riverpod annotations generate the boilerplate you'd otherwise write by hand. It's the state management solution that actually scales beyond three providers without turning into a BuildContext archaeology dig.

spotify_sdk for Spotify playback control and flutter_web_auth_2 for the OAuth 2.0 flow. The auth flow is the part that will make you briefly consider quitting software development. Then it works and you forget.

just_audio for offline playback. Rock solid, cross-platform, handles every audio format I threw at it. The seek precision on local files is significantly better than Spotify's remote playback latency, which is either satisfying or depressing depending on how you look at it.

Material 3 Expressive theming with dynamic colors. The UI pulls palette colors from album art. Your loop controller matches your album. It's completely unnecessary and I spent more time on it than I should have.

The Part Where I Justify This Whole Thing

I play guitar. Learning from recordings means looping the same passage repeatedly. Standard workflow: play the section, miss the end, seek back manually, miss the start, give up, play the whole song again.

With Pulse Loop: set start marker, set end marker, play. The 8-bar passage repeats until your fingers get it right. No seeking. No distraction. The loop is just there, waiting, patient, accurate to the millisecond.

This is the entire reason the project exists. Everything else — the Skip mode, the offline support, the dynamic theming — is scope creep that turned out to be genuinely useful.

Is This Worth It Over Just Scrubbing Manually?

The seek bar on a phone screen, at the precision needed for a 4-second riff inside a 4-minute track, is basically a game of chance. You will miss. Repeatedly.

Pulse Loop sets the markers once. They stay. Every time that track plays, the loop is already there.

Spotify won't build this. They've had twenty years and chose not to. That feature gap is the entire reason this exists, and honestly, I'm fine with that.

Open source. Free. Works right now.

• Source on GitHub
• Try it live

Go loop the good part. The 8 bars that actually hit. Because Spotify certainly isn't going to help you find them.

"If your app doesn't morph, bounce, or use 15 different shades of mauve, are you even designing in 2026?"

Let's be honest: most Flutter apps look exactly like someone ran flutter create, added a few Center widgets, picked a primary color, and shipped it. Standard pill buttons. Standard app bar. Standard "I copied this directly from a 2021 tutorial and never looked back" energy.

It's everywhere. Your users notice. They just haven't uninstalled you yet.

Google's answer arrived in May 2025: Material 3 Expressive (M3E). The most research-backed update to Material Design ever shipped. Specifically engineered for the crime of playing it safe. If your buttons don't have spring physics and your containers are still hardcoded to BorderRadius.circular(8), M3E is here to make that feel embarrassing.

The "I'm Not Reading 80 Pages of Design Spec" Summary

M3E — announced May 2025, still dodging mainstream adoption in 2026 because change is hard and CircularProgressIndicator technically works — is not a theme change. It's a fundamental shift in how interfaces feel. Four-point cheat sheet:

1. Color with purpose: Not "make the button blue." Using bold container colors to actively guide the user's eye instead of hoping they find the CTA themselves.
2. Shape flexibility: Buttons that morph. Containers that aren't just rectangles. Expressive active indicators. BorderRadius.circular(8) is retired. Let it go.
3. Springy physics: Spatial Springs for movement, Effects Springs for color transitions. Real objects bounce when you tap them. Linear easeInOut curves make your UI feel like a PowerPoint. Choose accordingly.
4. New components: Button groups, split buttons, wavy loading indicators. Yes, the wavy loader. It makes waiting for a network response feel almost deliberate.

My Buttons, Before and After

Before M3E: ElevatedButton with default styling. Technically a button. Communicates nothing about the emotional investment required to tap it.

After M3E: The same action, but the button has a physical presence. It responds. It has opinions about being pressed. Users notice this without being able to articulate why.

The research backs this up — M3E components tested higher for perceived quality, trustworthiness, and "this app was made by someone who cared." You can argue about whether spring physics are necessary. You cannot argue with conversion metrics.

The Components You're Still Not Using

The Wavy Loader (Upgrade From the Circle of Shame)

The standard CircularProgressIndicator says: "something is happening, probably, we'll see."

M3E's wavy loader says: "we are actively working on this and the app has not frozen."

These are meaningfully different messages. The wavy one looks alive. Ship the wavy one.

Button Groups and Split Buttons

Finally, grouped actions that don't look like you threw four individual buttons into a Row and called it done. Split buttons give you a primary action with an overflow option that stays in visual context. No more "wait, where's the secondary action" UX archaeology.

Spatial Springs and Effects Springs

Curves.easeInOut is retired. We are doing physics now.

Spatial Springs handle movement — the kind of bounce when an element enters or responds to a tap that makes the interaction feel physical rather than programmatic. Effects Springs handle color transitions — fades that feel organic rather than linear.

The math is non-trivial. The result is that your app feels premium without anyone being able to explain why. That's the goal.

The Workflow: Skip the Spec, Use an Agent

You could spend three days in the Material spec. Or you could point the material3-expressive-flutter skill at your AI coding agent and start shipping while it handles the implementation.

I've been using this skill to bridge the gap while official Flutter SDK support finishes catching up to the spec. It gives your agent the exact context needed to implement components correctly — not hallucinated approximations, not components that look close but break on the fourth interaction.

How to Get Started (Four Real Steps)

1. Enable Material 3: useMaterial3: true in your ThemeData. Non-negotiable table stakes.
2. Use ColorScheme.fromSeed: Stop manually typing hex codes. Dynamic palettes exist. Let them work.
3. Point your agent at the skill: The material3-expressive-flutter reference files cover the components that aren't in the SDK yet. Force it to read the spec so you don't have to.
4. Embrace shape morphing: Use the shape packages. BorderRadius.circular(8) has had a good run. It's done now.

The Result

When you combine M3E principles with proper motion physics, you get an app that feels like it was made on purpose. No more "this looks like a template" feedback. No more "did you build this yourself?" in a tone that implies doubt.

Conclusion

M3E is the difference between a utility tool and an actual experience. Your users don't know what spring physics are. They just know your app feels better than the other one.

Install the skill. Let the agent handle the physics math. Stop shipping gray-on-white list views.

Or don't. It is genuinely your call. The CircularProgressIndicator will still be there.

Next Steps:

• Check out the M3E Agent Skills repo for more details.

Written while my AI agent refactored 50 buttons to use springy animations because I refused to do it manually.

Or: How I Spent a Week Learning That Python Was Already Good At Everything Except This

So there I was with a perfectly functional React + Vite dashboard. Clean TypeScript. 260 lines. Fast builds. It worked. Users were happy. Life was good.

Then I had the worst kind of idea: "Let's rewrite it in Python."

I was the one who said it. I have no one else to blame. I went in voluntarily. The retrospective was not kind.

"It'll Be Easy," The Docs Lied

"Reflex is just Python." That's what the GitHub readme said. "You won't even need to touch JavaScript," tech Twitter added, with the confidence of someone who has never actually shipped this.

Narrator: It was not just Python. The JavaScript simply hid in the shadows and waited.

What I Expected

# Beautiful, Pythonic code that definitely just works
def dashboard():
    return render_my_beautiful_ui()

# Beautiful, Pythonic code that definitely just works
def dashboard():
    return render_my_beautiful_ui()

What I Got

# This is React with extra steps, worse autocomplete, and a confused IDE
def business_row(business: dict) -> rx.Component:
    return rx.table.row(
        rx.table.cell(
            rx.hstack(
                rx.box(
                    rx.icon("building-2", size=18, style={"color": COLORS["mauve"]}),
                    style={"background": COLORS["surface0"]},
                    class_name="w-10 h-10 rounded-full flex items-center justify-center",
                ),
                # ... 50 more lines of this

# This is React with extra steps, worse autocomplete, and a confused IDE
def business_row(business: dict) -> rx.Component:
    return rx.table.row(
        rx.table.cell(
            rx.hstack(
                rx.box(
                    rx.icon("building-2", size=18, style={"color": COLORS["mauve"]}),
                    style={"background": COLORS["surface0"]},
                    class_name="w-10 h-10 rounded-full flex items-center justify-center",
                ),
                # ... 50 more lines of this

class_name. style. rx.hstack. Bro. This is JSX wearing a Python trench coat. I rewrote React. In Python. The React is still there. It's just hiding.

The "Python Experience" I Was Promised vs. What I Received

String Concatenation? That's a Legacy Feature Now.

Remember simple string concatenation? Gone.

Before (React):

<img src={`https://s3.amazonaws.com/${image}`} />

<img src={`https://s3.amazonaws.com/${image}`} />

After (Reflex):

rx.image(
    src="https://s3.amazonaws.com/" + log["personImage"].to(str),
    # Because log["personImage"] isn't a string.
    # It's a Var. A special Reflex type.
    # That you need to explicitly cast to a string.
    # In Python.
    # The language literally famous for duck typing.
    # We are doing explicit string casting in duck typing Python. Let that sink in.
)

rx.image(
    src="https://s3.amazonaws.com/" + log["personImage"].to(str),
    # Because log["personImage"] isn't a string.
    # It's a Var. A special Reflex type.
    # That you need to explicitly cast to a string.
    # In Python.
    # The language literally famous for duck typing.
    # We are doing explicit string casting in duck typing Python. Let that sink in.
)

Empty Strings: Straight to Jail.

My favorite error message of the entire ordeal:

Error: A <Select.Item /> must have a value prop that is not an empty string.

Error: A <Select.Item /> must have a value prop that is not an empty string.

The underlying React component — which I am not supposed to be thinking about because this is Python now — was offended by an empty string. So I had to create a __all__ sentinel value and convert it back to an empty string in the state handler. In Python. Where "" is a perfectly valid falsy value that the entire language ecosystem accepts without complaint.

Beautiful architecture. Truly.

Styling: Tailwind Strings in a Python File That Compiles to React

"Use Tailwind," they said. So I did.

class_name="rounded-xl border p-5 hover:border-[#45475a] transition-colors duration-200"

class_name="rounded-xl border p-5 hover:border-[#45475a] transition-colors duration-200"

This is HTML. With extra steps. I am writing Tailwind class strings in Python, which Reflex compiles to React, which renders to HTML. Three layers of indirection to write what a .tsx file would give me directly — with syntax highlighting, autocomplete, and type checking via the Tailwind VS Code extension.

Instead, my IDE thinks I'm writing a very long, very sad novel.

The Build Process Comparison Nobody Asked For

React + Vite:

• npm run dev — 200ms. I sneeze and it's running.
• Hot reload — instant.
• Build — 2 seconds.

Reflex:

• reflex run — wait for Python to initialize.
• Wait for Reflex to compile the AST.
• Wait for the frontend to build. (It spins up Node anyway. We're running Node. In the Python framework. Outstanding.)
• Wait for the backend to start.
• Changed a component's padding? Full recompile. See you in 30 seconds.
• Port 8000 in use? Cool, we'll use 8001. Now your API calls all fail silently.
• Please enjoy these Pydantic v1 deprecation warnings as a complimentary side dish.

The Definitive List of Benefits of Reflex Over React

Here it is. Complete and unabridged.

1. You write "Python" instead of JavaScript.
2. ...
3. That's it. That's the full value proposition.

Except you're not actually writing Python. You're writing React component trees using Python syntax. You still think in components. You still manage state like hooks. You still write Tailwind strings. The only real change is the language — and that language is demonstrably worse at this specific task because it wasn't designed for the DOM.

The actual differences you get:

• Worse error messages (stack traces that cross a language barrier are a special kind of chaos)
• Slower build times (you run Python AND Node)
• A massive abstraction layer you cannot debug when it breaks
• Documentation described as "rapidly evolving," which is documentation-speak for "incomplete"

The Final Tally

Before (React): 260 lines of TypeScript. Fast dev loop. Immediate feedback.

After (Reflex): 456 lines of Python. Var types pretending to be Python while outputting JS strings. Slower everything.

Both versions: Still compile to React. Still need Node. Still run JavaScript in the browser.

We added Python as a middleman to a pipeline that begins and ends with JavaScript. Python, the language, is acting as a transpiler for React. We played ourselves at championship level.

Why Does This Framework Exist?

Honest question. The pitch is "write web apps in Python." The reality is "write React in Python syntax while fighting type systems that make no sense and watching builds measured in geological time."

If you want Python: use FastAPI. Use Django. Use HTMX if you need interactivity without touching JS. These are proven tools designed for the exact tasks they perform.

If you want a modern SPA: write React. Or Svelte. Or Vue. Anything where the tooling was built for the DOM.

Don't use a framework trying to be both that ends up failing at both.

Hot Take Conclusion

Would I recommend Reflex? Only if you:

• Actively enjoy debugging type systems that shouldn't exist.
• Need a legitimate reason to get up and make coffee while your frontend "compiles."
• Believe "it's Python so it must be simpler" is a valid architectural decision and not just a coping mechanism.

For everyone else: learn React. One weekend. You'll be infinitely more productive, your tooling will work, and you won't find yourself casting duck-typed variables to strings before a string concatenation.

If you enjoy staring at code that shouldn't exist, here's the project I migrated:

Written while waiting for Reflex to recompile for the 47th time today.

"If you aren't shipping features while your friends are paying $20 for a mid drink at the club, are you even a dev?"

Nobody: Me at 2 AM in an Uber: opens Termux

Welcome to Doom Coding — doom scrolling except instead of passively destroying your attention span, you're actively destroying your work-life balance. More productive. Same outcome.

While normal people "go outside" and "exist in the physical world," we're SSH-ing into production from the back of a ride-share. Is it healthy? Incredible question, we're moving on.

After this 5-minute setup, you'll be able to code anywhere you have cell service. Even in the air. Even on a run. Even at the club. These are all real options you will have. Whether you should use them is a completely separate conversation.

Literally higher than your server's uptime. Zone 2 heart rate. Production logs open. Living the dream.

The Stack (Minimalism Is for People Who've Never Had Scope Creep)

The Holy Quadrinity of mobile dev enlightenment:

1. Termux: Your new home. A terminal emulator that turns your $1,200 TikTok consumption device into an actual power tool.
2. Node.js/Bun: Because of course we're using JavaScript environments. It's 2026.
3. Claude Code: The paid AI deity for people with budget lines.
4. OpenCode + Antigravity Auth: The "I have principles" AI deity for everyone aggressively dodging API metering.

Step 1: The Sacrifice (Termux Setup)

Download Termux. Not from the Play Store. That version is archaeological. Get it from F-Droid or GitHub like someone who reads changelogs.

Open it up and run the ritual:

pkg update && pkg upgrade

pkg update && pkg upgrade

Install Ubuntu (no, I don't care about your Alpine evangelism, I want apt-get to work):

pkg install proot-distro
proot-distro install ubuntu
proot-distro login ubuntu

pkg install proot-distro
proot-distro install ubuntu
proot-distro login ubuntu

Update your brand new chroot:

apt update && apt upgrade -y
apt install curl git nodejs npm -y

apt update && apt upgrade -y
apt install curl git nodejs npm -y

Congratulations. Your phone is now a development machine. You can tell people you "work entirely in the terminal" while waiting for your cold brew. They won't know what that means. It'll feel good anyway.

Step 2: Choose Your AI Deity

Two paths. One has a monthly billing cycle. The other has character.

Path A: The "I Have a Budget Line for This" Option (Claude Code)

If you're fine with paying Anthropic to technically do your job while you drink coffee:

curl -fsSL https://claude.ai/install.sh | bash
claude --remote

curl -fsSL https://claude.ai/install.sh | bash
claude --remote

Done. Go back to your avocado toast.

Path B: The "I Have Principles" Option (OpenCode + Antigravity Auth)

For those of us who prefer to keep money for important things — RAM, mechanical switches, that one keyboard you've been eyeing for six months.

We use OpenCode.

I found the Antigravity plugin while responsibly not doom-scrolling, and it genuinely simplified my life. No monthly AI subscription just to get an LLM to tell me why my regex is objectively wrong.

Install OpenCode:

curl -fsSL https://opencode.ai/install | bash

curl -fsSL https://opencode.ai/install | bash

Now add the Antigravity Auth plugin. This lets you tap Google's Gemini and Claude quotas via OAuth like someone who knows how OAuth works.

Edit your config at ~/.config/opencode/opencode.json (yes, with nano on your phone screen, you can do it, I believe in you):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-antigravity-auth@latest"],
  "provider": {
    "google": {
      "models": {
        // Paste the Antigravity auth schema here for all the free-tier models.
        // I'm not pasting all 60 lines. Figure it out.
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-antigravity-auth@latest"],
  "provider": {
    "google": {
      "models": {
        // Paste the Antigravity auth schema here for all the free-tier models.
        // I'm not pasting all 60 lines. Figure it out.
      }
    }
  }
}

Now login:

opencode auth login

opencode auth login

CRITICAL NOTE: Android Termux does not support the full OpenCode TUI natively unless you have the patience of someone who has never experienced latency. You're a terminal purist now. Use the --web flag or your screen will look like it's having a medical event.

opencode web --hostname [YOUR_TAILSCALE_IP] --port 4096

opencode web --hostname [YOUR_TAILSCALE_IP] --port 4096

Step 3: Tailscale (The Packet Wormhole)

Running opencode web means your browser needs to reach that proot-distro Ubuntu instance without Android's sandbox filing a complaint. Enter Tailscale.

1. Install the app. It's in the Play Store. This one you can get from there.
2. Login. Use the same account you use everywhere else.
3. Turn it on. You're now part of the mesh.

Find your phone's Tailscale IP — the one that looks like 100.x.y.z. That is your new identity. Use it in the opencode web command so you can hit your dev environment from Chrome, or from your laptop if you're feeling spectacularly lazy.

Step 4: Ascend to Godhood

You are now coding from something that fits in your pocket.

You can push to production at a farmers market. Fix a bug during a movie. Ship features between sets at the gym. All of these are real actions you can now take. None of them are actions you should take without thinking carefully about your life choices first.

Pro Tips for the Committed

• Document everything: Always ask your AI to update CLAUDE.md or SHIPPING.md. Your future coherent self will be grateful that your 2 AM self left notes.
• The Club Protocol: If you're coding at the club, crank the brightness to max. Everyone should know you are categorically more important than whatever the DJ is doing right now.

Me when the drop hits but the prod logs are showing 500s.

Troubleshooting (Otherwise Known As Skill Issues)

If it doesn't work:

1. Termux Sleep: Android loves murdering background processes. Enable "Keep CPU awake" in the Termux notification tray or your session dies faster than a startup with no runway.
2. Node version drama: If npm acts up, pkg reinstall nodejs-lts. Do not negotiate with it.
3. OpenCode TUI: I told you. Use --web. If you forgot: classic skill issue. Noted for the retrospective.

Happy Doom Coding. Go ship something before the concept of "healthy work-life balance" accidentally enters your mind and ruins everything.

Writing code is easy. Reviewing your own code is functionally impossible because you already convinced yourself it was fine an hour ago.

You know that moment. Cursor hovering over the commit button. The cold creep of dread. Did you leave a console.log("here") in? Did you break a type in a file you only vaguely remember touching? Did you rename that variable to something embarrassing?

You have two options:

1. Scroll through the diff, lie to yourself, and push to master.
2. Manually open Copilot Chat, paste the diff, ask it to review, wait, context-switch back, forget what you were doing.

Option 1 leads to PR comments that age poorly. Option 2 is a full flow-killing chore that requires so much ceremony you never actually do it.

What if the AI just... watched?

Making Staging Aggressively Judgemental

I built a VS Code extension that hooks into the Git API. Every time you stage a file — git add, the little + button, however you do it — Auto Copilot Review wakes up, grabs the diff of everything staged, and fires it straight into GitHub Copilot Chat with a review request.

Zero clicks. Zero context-switching. You stage a file, you glance right, and there's already a breakdown of your logic problems waiting for you like a very patient disappointed parent.

It happens entirely in the background. The extension doesn't ask. It doesn't warn you. It just starts judging.

The "God, Slow Down" Problem

My first build was too eager. Embarrassingly eager.

I stage files by rapidly clicking + on five different files in a row, which in V1 meant five simultaneous Copilot API requests firing within one second. The Chat panel had a complete breakdown — five competing reviews flashing at once, each overwriting the last. It looked like a merge conflict with extra steps.

Turns out teaching a machine to review your code also means teaching it patience.

I added a configurable debounce timer — default 5 seconds. Now you can stage as frantically as you want. Once you stop moving for 5 seconds, everything gets bundled into a single review request. One clean response. No chaos.

It's a small thing. It's the thing that made it actually usable.

The Part Where It Actually Works

Within seconds of staging: a clean breakdown of your logic flaws, typos, forgotten debug statements, and edge cases you were hoping nobody would notice.

It feels like having an extremely pedantic code reviewer permanently installed on your shoulder, waiting for exactly the moment you're about to commit something embarrassing so they can quietly intervene.

The best part is it requires genuinely nothing from you after install. No commands. No shortcuts. No workflow changes. It just exists, watching, reviewing, and silently saving you from the PR comments that would have aged very badly.

Is it humbling? Yes. Does it catch things you'd have shipped? Also yes.

If you have a Copilot subscription and a realistic assessment of your late-night coding judgment, install the extension. Your future self — the one reading PR comments — will thank you.

The fashion industry loses $400 billion a year to returns. Me: I'll fix it. With PHP. Everyone: ... Me: And a modal.

Look, I could have built a custom vision transformer. Trained it on proprietary fashion datasets. Deployed it on a GPU cluster. Applied for Series A funding and put "AI/ML Engineer" in my LinkedIn bio.

Instead I wrote a WordPress plugin.

The fitting room still works. The VC funding was unnecessary.

The Problem Is Embarrassingly Real

You can't try clothes on through a screen. So you buy three sizes, keep one, return two. The warehouse restocks it. The planet suffers. Customer service handles the complaints. Everyone loses except the shipping company.

This problem has an obvious solution that somehow costs $99/month if you want the branded SaaS version of it.

So I built the unbranded version. It's called tryon-modal. It's open source. It takes longer to read this post than to get it running.

"It's Just a WordPress Plugin" — Yes. And?

WooCommerce runs on 30% of all e-commerce sites. If you're targeting fashion stores, you're targeting WordPress. That's not a compromise — that's a distribution strategy.

Also, PHP 8 has named arguments, enums, fibers, union types, and a JIT compiler. If you're still dunking on PHP in 2025, that tweet isn't landing the way you think it is.

The AI Part (Which Is Embarrassingly Simple)

Everyone imagines "AI virtual try-on" means a six-month research sprint and a team of computer vision PhDs.

What it actually means in 2025: Google Gemini's multimodal API already understands images, garments, and human figures. So instead of training anything, you send it three things:

1. The user's photo
2. The garment image
3. A prompt that is genuinely just English sentences

And it gives you back a try-on composite. The "AI research" was writing a good prompt and a clean PHP API handler.

// This is the entire AI integration. Don't overthink it.
$response = $this->gemini->generateContent([
  'parts' => [
    ['text' => $this->buildTryOnPrompt($garmentCategory)],
    ['inline_data' => ['mime_type' => 'image/jpeg', 'data' => $userPhotoBase64]],
    ['inline_data' => ['mime_type' => 'image/jpeg', 'data' => $garmentImageBase64]],
  ]
]);

That's it. That's the model call. The rest is plumbing.

The Garment Mapper: My Favorite Feature Nobody Will Tweet About

Here's the thing about Gemini: the prompt needs context. "Is this a top or a dress?" changes the output quality significantly. Wildly, visibly significantly.

So I built a Garment Mapper — an admin UI where store owners bulk-tag their product images as Tops, Bottoms, Dresses, Outerwear, etc. The tagging feeds into buildTryOnPrompt(). The prompt changes. The results get noticeably better.

It's the most impactful feature in the plugin and the least glamorous one to explain. That is the software development experience in a single sentence.

Security: The Part Nobody Claps For

A plugin that accepts user-uploaded photos and routes them to an external API has real attack surfaces. So we do the boring-but-correct stuff:

• Nonces on every AJAX action (CSRF protection, WordPress-style)
• esc_html() and sanitize_* everywhere user data touches the DOM
• $wpdb->prepare() on every database query — no raw SQL, ever
• MIME type validation on uploaded photos before they go anywhere near Gemini
• HTTPS enforcement on all API calls

Nobody writes blog posts about not having CVEs. The alternative is worse.

The Modal: Invisible Until Needed

The worst thing a plugin can do is slow down a product page. So the modal loads nothing — zero CSS, zero JS overhead — until the user clicks Virtual Try-On. Then it bootstraps the whole UI on demand.

Once open, it supports:

• Drag-and-drop photo upload with live preview
• A results pane that fades in when Gemini responds
• A download button for the try-on image
• An Add to Cart button inside the modal — no page navigation required

The whole thing is namespaced under nano-tryon-* CSS classes so theme overrides work without touching plugin files. Because !important-ing your plugin styles into the host theme is a war crime.

Session History: Two SQL Queries, Actually Useful

Try-on sessions get stored in wp_tryon_sessions — image paths, garment used, timestamp, user ID. Users can revisit what looked good before buying.

Could I have skipped it? Yes. Did I? No. Users who come back and check what they tried on last week convert better than users who don't. It cost two SQL queries and a loop. The ROI math is straightforward.

Does It Work?

Yes. Upload a photo, pick a product, wait a few seconds, see yourself wearing it — without leaving the product page, without an account on a third-party app, without a $99/month subscription.

A WooCommerce store. A Gemini API key. A five-minute install.

Sometimes the unsexy tool for the unsexy platform solves the real problem better than the venture-backed alternative. Sometimes the fitting room is a PHP modal.

The code is open source on GitHub. Your Gemini API key is free up to a quota that will absolutely cover your first thousand try-ons.