How I built a photo app by directing AI, and what went wrong along the way

The first commit is a 228-line Python script called PhotoRanker. It opens a Tkinter window and shows two photos side by side. You click the better one. It updates a chess-style Elo rating for both photos, then shows the next pair.

A 1 to 5 star scale is hard to keep consistent. After a few shoots it is unclear whether a given sunset is a 4 or a 5. Elo avoids that question. Each click is one small comparison, and thousands of them produce one overall order. The script also pairs the current top ten against each other more often, so the leaders get tested the most.

In February 2026 the project restarts as a web app in two commits. The Tkinter window becomes a FastAPI server and a dark HTML page. The more important change is how comparisons are made.

Instead of two photos at a time, there is now a mosaic: a grid of candidates. You pick the best one, and all the others lose a little rating. Each click gives more information and is less tiring. The Elo math is the same.

April 21 is the most important day in the history. The commits that day, in order:

CLIP active learning, a unified bottom bar, an AI panel with effective-Elo pairing, a Library page with a justified grid and AI search, the Qwen3-VL-Embedding-8B model for search, the rename PhotoRanker to photoArchive, a lightbox, find-similar, duplicate detection, EXIF, k-means auto-collections, and finally Qwen3-VL-2B-int4 "to fit the GPU alongside other apps."

The main change: the library no longer needs typed tags. Embeddings turn each photo into a vector. With vectors you can search for "golden hour over water" in plain language, find photos similar to one you like, and group a shoot automatically, all without keywords.

With search in place, the next four days were spent on speed. Most of the gains came from the same change: stop reading from the slow disk, and answer from memory instead.

The biggest gain was thumbnails, 30 to 50 times faster. Every thumbnail request was calling os.stat() on a spinning hard drive and doing a SQLite lookup under a lock, even for images already on the SSD. The fix was to build a (size, image_id) → path dictionary once at startup and never touch the database on that path again.

Over one weekend about 130 commits landed with names like refactor: drain compare route facades. The single app.py was split into feature modules. The thumbnail cache became its own package. Every route and controller (loupe, mosaic, date scrubber, pregeneration) was moved into its own place.

It was slow, repetitive work. A RAW editor could not have been added to a ten-thousand-line file, so the later chapters depend on this weekend.

By summer the plan was clear. On the phone, the app should feel like Google Photos: easy scrolling, one hand. On the desktop, it should feel like Lightroom Classic: dense, keyboard-driven. In June a native Kotlin and Compose Android client started. In early July the desktop /d and mobile /m pages were redesigned together, with real writes, stacks, a safe trash, share links and smart collections.

In three days a full RAW editor was added: a live WebGL2 pipeline with panels in Lightroom's order, a tone curve, HSL, a clipping histogram, crop, masking and history. It also had its own RAW decoder, its own colour science, and a film emulation engine that models the chemistry of film.

Every editing operation exists twice: once in NumPy, which produces the exported file, and once in GLSL, which draws the live preview. If they disagree, an edit looks one way on screen and exports another way. To prevent that, both versions read one shared table of constants, and a test checks that they match within 0.4 of 255 on every pixel, across 53 operations.

film.py is a film emulation engine that models the physical process. It is not a LUT or a colour grade. It models spectral exposure of each layer, halation, H&D characteristic curves, DIR coupler inhibition, and grain per layer. The red glow around bright lights on CineStill 800T is not painted on. It comes from the model: bright light reflects off the film base and back into the red-sensitive layer.

LibRaw cannot open Lightroom's lossy DNG files (JPEG XL, DNG 1.7). So the editor got its own decoder. It reads the LinearRaw image data directly and applies the DNG colour pipeline by hand: black and white levels, AsShotNeutral white balance, ForwardMatrix to XYZ, a Bradford-adapted matrix to linear sRGB, and BaselineExposure. A 2048px image decodes in 0.4 seconds, and the output was calibrated against my own Lightroom exports.

The phone and desktop apps from Chapter 05 needed to share one library. So the app gained a satellite and hub design: a copy of the catalog on the laptop, thumbnails in tiers, prefetching, and an operation log that syncs later instead of a request that waits. The rule was that the laptop never waits on the server. You cull on a plane, and it syncs when you land. Location backfill, a Google Timeline importer and keyword and IPTC support were added in the same week.

photoArchive became Azimuth Photo. The new name went on the wordmark, the web app manifest, the Android launcher and the desktop shell, and bundle IDs moved to app.azimuthphoto.*. Internal names, paths and database names were left alone so work in progress would not break. A Docker image, a compose file, an Unraid template and an INSTALL.md made it installable on a NAS. An Android client with a timeline, auto-backup and free-up-space shipped the same week.

The first twenty days of July have 1,226 commits, three quarters of the whole project up to then. They follow a set structure: a written charter for work lanes, roles named "CEO / CTO / managers / subagents", and hundreds of merges from named branches such as qfix-workers, ux2-perf, errhonesty and dt-gfilter. I directed several AI models, each working in its own lane, with one fixed rule: a different model reviews every change, never the one that wrote it.

The models were good at producing software. On their own, they did not check whether it was the right software.

Every lane finished its tasks. Every merge was reviewed. The tests passed. But 24% of the 2,203 commit subjects were repairs (fixes, hotfixes, regressions), and simple changes were taking days. It took me a while to see that those were the same problem.

In August I wrote down one sentence that changed the plan.

I measured the live catalog. 2.4 GB across 84 tables, and 41 of those tables were empty. They had been built, connected and tested, and never held a row.

Then the main question. In the 43 tables that did hold data, how much was a decision a person made: a keep, a star, an edit, a name? Everything else was computed from the photos and could be computed again.

That number changed how I saw the previous two years. The extra tables were not protecting anything important. They were bookkeeping: backlogs of work still to do, cursors that remembered progress, tables recording what each disk held, and more tables keeping those in agreement. Stored data that you do not need still has a cost, because it has to be kept consistent.

It also meant that the smaller design was the safer one.

The reason: a codebase is something you and your tools have to find your way around. Every unused subsystem makes every later change slower and harder to understand.

The deletions went in waves, each one passing its tests, with git history keeping the old code:

I also kept a record of the deletions that were wrong. The commit subjects say so:

Since 99.94% of the catalog could be recomputed, a much smaller design was possible. Azimuth needs to know four things about a photo: what it is (its bytes), where its copies are, what you decided about it, and what was computed from it. Only the third cannot be recreated.

Those four facts became five tables and seven functions:

The most useful change in the rewrite fits in one line, and it explains years of bugs:

That one choice caused the drive probing, the hub_remote column, missing_at, the mass-missing safety check and rebind_moved_source. Five subsystems, all trying to recover a drive letter from a stored path string. They were careful, tested code, but they only existed because of how the path was stored.

Storing the tail and computing the full path fixed this. A renamed folder is now one row. A new drive letter is one row. The same photo on two disks is just two copy records. The five subsystems were deleted because nothing needed them.

The same approach worked for background work. The backlog tables, progress records and resume cursors all answered one question: what still needs doing? Asking that as a query, instead of storing the answer, reduces it to one anti-join: photos with no cache row of a given kind. There is nothing to resume and nothing to clean up when a worker stops.

The results, measured on the live 157,000-photo catalog. The grid got faster without a new cache: 86 indexes on one table went down to 5. Most of them were kept up to date for queries that no longer ran.

A well-known example is from 1986. Jon Bentley set a word-frequency problem in his Programming Pearls column. Donald Knuth answered with a literate program in WEB/Pascal: more than ten pages, a custom data structure, fully documented. Doug McIlroy answered with six shell commands.

So the more carefully crafted program was the less elegant one. Elegance was not in the workmanship. It was in seeing that the problem could be solved with what already existed.

Dijkstra's definition, taken from a dictionary, is "ingeniously simple and effective." Both parts matter. A shorter program that does less is not more elegant.

From that definition, extra code builds up wherever the program's model of the problem differs from the real problem. Each wrapper, flag, safety check and status column covers one of those differences. So refactoring means correcting the model. The extra code can then be removed, because it only existed to cover the difference.

Other authors reach similar conclusions. Ousterhout defines complexity as dependencies plus obscurity, which makes readability part of the technical definition. Hickey's term is complecting, the braiding together of two things: many copies of a thing do not make a system complex, but interleaving does. Brooks splits difficulty into essential and accidental, and notes that a tenfold gain from tools would require accidental difficulty to be more than 90% of the work.

Hickey's other distinction is the one I use most. Simple is objective: you can see it in the code. Easy is relative to the person: familiar code feels simple even when it is not.

The common rule is that big files are bad. But research on software metrics gives a reason to doubt it. In a study of a large industrial C++ system with faults traced to real failures, the standard object-oriented metrics predicted faults only until class size was taken into account. After that, none of them held up. The authors set a test that any metric should pass:

Does the metric predict defects beyond what size predicts?

I ran that test here: 312 source files, 2,304 commits, tests excluded. The outcome is how many repair commits touch a file. The coupling measure is how many non-repair commits touch it, so the predictor and the outcome do not overlap.

The clearest example is web/app.py. It is 120 lines and has the most repairs per line in the repository, because every part of the app is assembled there. By size it looks like the safest file. By coupling it is the riskiest, and coupling was right.

The practical result: instead of asking how big a file is, ask how often unrelated work has to change it. Git history on any repository can answer that without extra tools.

Richard Gabriel's Worse Is Better is often cited as proof that practical code beats elegant code. Reading it, the argument is about growing a system in small working steps, close to Gall's law: a complex system that works has usually grown from a simple system that worked. It is not an argument for low quality. Gabriel later argued the opposite side himself under a pseudonym, and at a panel a decade later he submitted papers for both positions and said he still could not decide.

The useful part is how he describes the two sides. Both value simplicity. They differ on where the simplicity goes: one side puts a simple interface first, the other puts a simple implementation first. That is a question of whose work you make easier, the caller's or the implementer's. Ousterhout's "deep module" is the first position written as a rule.

Carmack is often quoted against small functions, but his reason is not speed or readability. It is state: moving code into a named function lets someone call it later to do a partial update, and many bugs come from the program's state differing from what the programmer expects. His 2014 follow-up says the real goal is controlling unexpected dependencies and changes, and inlining is only one weak way to do it. He also rates duplication as worse than the problems shared functions cause.

Sandi Metz says the opposite: duplication is cheaper than the wrong abstraction. Her reasoning: a requirement arrives that almost fits, someone adds a parameter and a condition instead of rethinking the abstraction, and after a few rounds it is full of special cases. People keep it because existing code looks necessary. Her fix is to copy the code back into every caller, delete what each caller does not need, and then design the abstraction again.

Every model I used could write good code. Most of the bad code I got was my fault: I asked for a task instead of a design, accepted the first thing that worked, and took its word that it was finished. First, here is what research has measured about AI-assisted development:

Two things there changed how I work. The first is GitClear's explanation, which I agree with: the problem is how the tools are used, not the models. Assistants are used to produce as much code as possible, and that produces copying and rework. My own July matches that: 1,491 commits, and nearly a third of them were repairs.

The second is METR's finding that AI helps least in codebases with high standards and many unwritten requirements. In other words, AI helps least where the code is already good. As a codebase improves, the work shifts from writing to deciding, and the deciding has to come from you.

None of these are clever. Most of them just refuse the first answer that works.

Enforce rules in code. "A recipe is never a timestamp" sat in a comment for a year and was broken anyway, by me and by every model that worked on it. It stopped being broken when it became a function that raises an error.

Do not keep retrying bad output. When something came back poor, my first reaction was to explain more and try again. That usually cost more than doing it myself, because the second attempt kept the design of the first. Now a weak result means I do that piece myself.

After Act II there was a small core with no screens on top of it. The old screens came with routes, a port, a login layer and session handling. All of that was for outside visitors, and there were none: every request came from the same laptop.

On 18 August the server was removed in 34 commits, each deleting what it replaced. What remains is one Python process that opens one native window showing one HTML document. The page talks to Python through one bridge object. There is no HTTP and no port, so there is nothing exposed to secure.

To track what was finished, I added a second ledger, REWRITE_LEDGER.md. It lists every code file, and every file starts as "Legacy". A file stops being Legacy only when an entry says it was rebuilt and tested. A check fails if any file is missing from the list, so old files could not remain unnoticed.

Two other changes came out of the same week. The thumbnail store had its own routes, a cache table, a cleanup worker and versioned URLs. Without a server, a thumbnail is just a file the window reads, so all of that became a file name. The background worker used to check for work on a timer. Now it waits until a sweep, an import or a decision creates work.

Rank shows a set of photos and asks which is best. Each group in a set is shown at the same size, so no photo wins by being larger. Best is the order that results from these choices. There is no score table: each comparison is saved as a decision in the log, and the ranking is computed from the log and from how similar the photos are. The similarity part is why 310 judged photos could place 8,617 others.

Stars now come from the ranking. A photo's stars show where it falls in the ranking. Each extra star halves the set: one star is the top half of what you have judged, five stars the top 3%. A star can be earned against the whole library or within one shoot, and the info panel says which. The old judgements were carried over from the old catalog, which was opened read-only.

Search can find a photo three ways: by text (file name, folder, camera, date), by a set you named (an album or a label), or by meaning, using embeddings. Each way returns a list with its own kind of score, and a file-name match and a similarity score cannot be compared directly. So the lists are combined by position only: each photo gets 1/(60 + position) from every list it appears in. Turn a list off below: the results get worse, but there are still results.

Collections were simplified the same week. What you see is always one scope. An album is a saved set of photos, and a smart album is a saved search. Both use the same filter chips, so "2024 · Canon R5 · starred · in Iceland" is the same scope whether you typed it, saved it or clicked it.

The day started with a study of how Google Photos, Apple Photos, Lightroom, Capture One, Photo Mechanic, Excire, Peakto, PhotoPrism, Immich, Mylio and ACDSee organize a library. By the evening there was a working draft: suggested groups of similar photos, a shelf to hold the suggestions, seventy automatic tags, and a Keep button. I tried it on my real library and sent back a page of changes. This was the main one:

All the automatic suggestions were removed: the groups, the shelf, the tags and the Keep button. What stayed is one idea: a label is a word you teach. You search for it, mark the wrong results, and it improves from then on. Labels and smart albums turned out to be the same thing, so they use one formula: what the model predicts, plus what you added by hand, minus what you rejected.

This gave the app one consistent rule. Anything computed is a prediction and is shown with a tilde: Nightscapes ~74, a face that might be someone, a guess at where a shoot ends. Anything you say is a decision, saved permanently in the log, and it replaces the prediction. Ranking already worked this way.

People work the same way. The app finds faces and groups them, but it never decides who anyone is. A person is a name you give to a group of faces, and nothing else is stored about them. The same day, the app started using the same colours and compass logo as this website.

The request was an editor "nearly 1:1 with Lightroom Classic" that could open Lightroom's own edits. First I counted what that would require, by reading every edit file Lightroom had saved in my library:

The crop shipped first, then a full panel of sliders. The acceptance test compared its output with Adobe's on forty real DNG files: 0.0445 average difference in lightness, against a limit of 0.035. That did not pass, and the number was recorded in the design document. A few days later I looked at the panel, found it well short of Lightroom, and parked it. On 19 September I confirmed the decision: editing stays in Lightroom, and Azimuth is for browsing, searching, ranking, people and import.

The same weeks produced several features about the files themselves:

On 12 September the whole product was: five tables, 16,286 lines of Python, and an interface of 7,835 lines of JavaScript and 1,246 lines of CSS, bundled into the one document the window opens. The Android client was removed the next day.

I had expected to keep the 39,000-line interface. Instead, each screen rebuilt on the new core needed about a fifth of its old code. Most of the old interface had converted data between formats that the new core does not use.

V1 could be deleted safely because of a tool added the same day: tests that run the real app off screen. The window is created 2,400 pixels to the left of every monitor, where it still renders, and is captured with a Windows call that works wherever the window is. A script clicks and types in it first, so each screenshot shows the app after a real sequence of key presses.

Each script is a journey, one for each task a photographer does: cull with the keyboard, zoom in, name someone, find a photo from memory, judge a burst, make an album. After each round, I compare the screenshots with the previous round's. The Act III screenshots on this page came from these scripts.

I asked for a findings ledger. Each entry says what the problem does to the user, where it is in the code, the fix, and how much it matters. An entry closes only in the commit that does the work: shipped, or rejected with a written reason. When the ledger is empty, a new audit adds more.

After four days it had 555 entries. 102 of them came from a second model that read each day's changes and tried to prove them broken. It found a focused button that blocked Enter on every screen, a day selection that kept pages in memory, and a queued pick that stayed after its set had finished. A normal review had marked all of these as done.

On 12 September the old account could no longer be used. The code went to a new repository as one commit containing 254 files. The 2,632 earlier commits were uploaded as a branch called legacy-main, so every commit hash in this log still opens on GitHub. The project has 3,046 commits in total.

That evening the work moved to cloud sessions. Each task ran in its own session, pushed its own branch and opened a pull request, and every pull request was checked on Linux and Windows. More than thirty pull requests were merged that evening. The development library became public-domain photos that can be built on any machine, with a large set of 6,105 real photos. The audits were split: a cheaper model looks for problems, and a stronger model checks and fixes them.

Another addition that night was a friction meter. The app records how long each action takes while I use it, and I can press a key to mark something that annoys me. From then on, my own use of the app produced measurements.

The catalog the app opened contained one drive: the laptop's working drive, with about 7,600 photos. The archive, 3.2 TB on a USB disk, was only in an older catalog that the app no longer opened. Every "archive is missing" report came from that.

Adding the drive took a minute in the app's drive dialog. The sweep found 147,888 photos. But in the new design a photo's identity is a hash of all its bytes, and the old catalog's hashes were a different type that could not be reused. So every file on the 3.2 TB USB disk had to be read.

The next day I measured how fast the disk can be read. Every method gave about the same result:

The disk reads at about 35 MB/s no matter how it is read. One idea was to let only one lane read the archive at a time, so the disk head would move less. It was built, measured slower, and removed within the hour (0acbdf98, 173a5f31). The backup program reading the same disk made it about five times slower, and pausing it is my decision, not the app's.

This changed what counted as expensive. At 35 MB/s, identifying the whole archive would take about 25 hours. Each launch also scanned the archive's 1.5 million files before doing anything else: 57 minutes per launch. So during the backfill, the most expensive thing to do was restart the app.

Background work is a query: each of four lanes asks what is owed and takes the first item. Each photo goes through the same steps: identify it (hash its bytes), read it (camera, lens, date), make its thumbnail, and make its vector for search. With 111,414 photos waiting, the order of the list matters a lot.

Order 1: newest photo first. Nothing was identified for five minutes while thumbnails kept being made. A photo's date is only known after it has been read, so every unread photo sorted after every dated photo that still needed anything. The sort key depended on work that had not happened yet. Fix: unknown dates sort first.

Order 2: unknown dates first. Now reading went quickly and everything after it stopped: 19,191 photos were waiting for vectors and faces, so more and more of the library could not be searched by meaning. Fix: sort by the file's own modified time, which every photo has from the start and which does not change.

Order 3: newest file first. In this library, every photo that was already identified had a newer file than every photo still waiting. So identified photos always came first, and nothing was identified all night while the vector backlog was worked through and the archive disk was half idle.

You can run the three orders below. This is a small model of the real queue:

The fix that worked was not a fourth order. Each kind of work has its own newest-first list, and the lanes take the kinds in turn (bd527252). No single order can let one kind of work block the others, and the disk and the card both stay busy.

Those two nights had two more problems. On 15 September the laptop went to sleep at 21:46 in the middle of a step. The step failed and left its database transaction open, keeping the write lock, so the other three lanes timed out every minute until morning. The database log file grew to 1.4 GB, and every read afterwards had to go through it. Now a failed step rolls back, and the log is trimmed at every checkpoint (287dc362, a4293d75). The next night the app crashed at 01:42 with memory corruption: four lanes had been running the search model and the face models at the same time. Loading the models was protected by a lock, but running them was not. Now it is.

Two review rounds had taken over the work. Findings were closed one at a time, each correctly and each with its commit: seventy-one numbered findings in one afternoon and evening. But using the app, the ranking mode still lagged. I sent two messages that evening:

The work was narrowed to the problem I could see. The slow part of a Guided ranking question was that each pick re-read who was in the library, which a pick never changes. Keeping that result took a question from 1.37 s to 33 ms (b0659bb6). The ranking work was given to a different model to finish, with only one model writing each feature. The same night the app got a changelog in its menu and a blue "Restart to update" button. The next morning it got a menu bar: File, Edit, Library, Photo, View, Help.

The restart button was added because of something measured that day: my shortcut runs the source code directly. There is no install step, so every commit is what my next launch runs. That afternoon a worker bug that used 100% CPU was in the code for 22 minutes, and I happened not to launch during that time. After that, worker changes were tested on a copy of my library before being committed.

My message that night: "keep working until its all perfected and we squeeze every last drop of performance out of the hardware." All the tools were read-only: the app's own records of how long each action took, a profiler that samples without stopping the app, and the Windows disk and CPU counters. Anything that needed a query or a render ran on a copy of the catalog.

The records showed the four lanes spending 22 of every 57 lane-minutes asking what was owed: the same whole-library query, run once per lane. That became one shared list, queried once, with each item taken by one lane (ee8f4a21). Also, one lock covered every read of an original file, so the fast internal drive waited behind the slow USB drive. Now the lock covers only the archive (14656f13). Measured over the same fifteen-minute periods of the backfill:

After that, the USB disk was the limit again. During the night it read at 34.7 MB/s and was 90% busy, while the internal drive was 99% idle and the processor was 13% loaded. The code was no longer the limit. At 03:35 Windows Update restarted the laptop, closing the app and the session. The next launch continued from where the night had stopped.

The first problem: 191 files were on both drives, and 98 of them had different sizes, because Lightroom had written metadata into the working copies. Each drive's sweep saw the other drive's version, re-read the whole file, treated it as a new photo, and moved every decision to it. The next sweep moved them back. 3,103 identity changes since 20 September, and 19.3 GB re-read each time. My decision: "newer file wins, and we can update the data of the old version." The backup now replaces the older copy and moves it into the drive's own trash folder (74d96f1e).

The second problem was file names. Of 83,757 DNG files, 13,332 have the same name as a CR3 or CR2 raw file. "Same name, same photo" is often wrong: a camera numbers files from 0001 to 9999 and then starts again, so SKDA5202.CR3 from 2026 and SKDA5202.dng from 2024 are different photos. The rule that works also checks the capture time to the second and the camera. Try both rules:

The last change before this update: every launch ran a repair that read the edit log for about 36,000 photos one at a time, with one database write each. The database driver starts a write transaction before each write, so the repair held the write lock for about half a minute on every launch, even when nothing had changed. Now it reads the log once, writes only rows that differ, and starts no transaction when nothing has changed (e1204429).

The project started with one idea: it is hard to rate a photo, but easy to pick the better of two. Two years of extra code were added on top of it. Then a month was spent removing most of that code.

Writing code was not the hard part. With several models working, code was cheap. The hard part was deciding what should exist, and the models building it never answer that question.

Speed has to be protected. Measure first, and do not raise a time limit to hide a slow feature. That is how startup went from 65 s to about 5 s, and the grid from 180 ms to 0.22 ms, by removing 81 indexes instead of adding a cache.

The app should not report things it cannot back up. No success message before the save completes. No backup marked safe without checking the bytes. A live preview that must match the export within 0.4 of 255. A deletion record that lists the three deletions that were wrong.

Knowing what cannot be replaced made the deletions safe. The worst risk in three years was always losing a photo that cannot be recovered. Once I knew that only 0.06% of the catalog was irreplaceable, the rest could be deleted safely.

The best changes removed code. Five subsystems were deleted once a path was stored as a drive plus a tail. Every backlog and cursor became one anti-join. Noticing that a question is no longer asked is the one change I know of that makes a codebase both smaller and more capable.

A ledger is more reliable than a model's memory. The findings ledger now has more than 950 entries, and none closed without the commit that fixed it, a benchmark number or a screenshot. That is the only method I found that lets several models fix hundreds of small things without any of them quietly coming back.

Eventually the hardware is the limit. Once the code was small, the slowest part of the system was a USB disk reading at 35 MB/s, and the most expensive thing to do was restart the app. After that point, speed depends on the hardware and on how often you use it.

On 23 September: 3,046 commits and five tables. The product grew from 25,367 lines to about 32,250 in eleven days, for people, Guided ranking, a menu bar, a changelog and edit families. The next question is whether that growth was necessary. Editing is done in Lightroom. There is no phone app and no sharing yet.