📸 Introduction: a photography portfolio in production on day three

Framed by Santi is the website of @framedbysanti, an amateur photographer who shoots the streets of New York with a Fujifilm X100VI. It has two sides: a public site to show his photos and a private dashboard so he can publish on his own, without depending on anyone.

It started as a gift for a friend, but this post isn't about that: it's about how I built it in very little time, assisted by Claude Code, without giving up on quality.

The numbers, straight from the repository:

• 📅 9 days with commits, from October 13 to 26, 2026.
• 🚀 In production on day 3: public site and private dashboard.
• 🔀 189 commits and 35 pull requests; I tested every change myself, as a visitor and as the admin, before it reached production.
• 🧪 117 test files with 857 cases.
• 🌍 Three languages: English, Spanish and Portuguese.
• 💯 100 in all four Lighthouse categories (desktop, 4G network).

🤖 How I worked: AI agents, but with a method

I built it in the terminal with AI agents (Claude Code) configured through gentle-ai, the open-source tool by Alan Buscaglia (Gentleman Programming). This isn't "asking the AI for a website": it's a workflow with rules.

• ODD (Organic-Driven Development): small changes are made directly; big work gets a task document with the requirements copied word for word, so nothing gets lost between sessions.
• Engram: persistent memory. Every decision, solved bug or preference is saved and the agent recovers it in the next session. For example: "ask before pushing, even to staging".
• Tests first: for every new rule, first a failing test and then the code that makes it pass.
• Branches and review: every change starts on a branch, goes up to develop, I test it on staging, and it only reaches main (production) when I approve it.

The split was clear:

• 🤖 The agent: wrote the code and the tests, investigated the bugs, proposed solutions and opened the PRs.
• 🙋 Me: decided what to build and how it had to work, reviewed every change, corrected the agent when it got things wrong and approved every release to production.

💡 AI writes fast; what makes the result good is verifying. Every PR passed lint, tests and build, and no change reached production without my approval.

🧱 Stack and architecture

Frontend

• Angular 22 without Zone.js (zoneless), with Signals for all state and standalone components.
• TypeScript 6 in strict mode: no any and explicit return types.
• Native CSS with nesting, BEM and mobile-first. No preprocessor.
• Vite 8 with @analogjs/vite-plugin-angular as the only build tool.
• Transloco for the three languages.

Services

• Vercel: hosting and four serverless functions.
• Firebase Auth and Firestore: dashboard login and data (sets, themes, settings).
• Cloudinary: photo storage and delivery, with signed uploads.
• DeepL: automatic translation of the texts.
• Resend: the contact form email.

The four api/ functions

The three dashboard functions check that the user is an admin the same way: they read their document in Firestore with the user's own token, so it's the Firestore security rules that decide, not a secret on the server.

🖼️ The public site

• Posts are sets, like an Instagram carousel: several photos with a title and a story.
• Home with the latest set in a draggable carousel.
• Gallery with a section per set and a theme filter.
• Full-screen viewer: zoom and pan (pinch, drag, double tap, wheel), swipe gestures, thumbnails, preloading of the next photo and a dissolve between photos.
• View Transitions between pages, with an iris effect like a camera aperture.
• About with Santi's story in his own words and a contact form. His email never reaches the page.
• Real languages: dates, numbers and plurals follow the active language (en-US, es-ES, pt-PT).
• With prefers-reduced-motion, nothing animates.

The home page. Click to see it live.

The gallery with the theme filter.

The viewer: zoom, arrows and thumbnails.

🔐 The private dashboard

The dashboard lives at /admin and has no public link: you only get there by typing the path.

• Set library: published or draft switch, edit and delete.
• Set editor: drag photos in, preview them, reorder them and write the texts in one tab per language.
• Photos prepared in the browser: before uploading, each photo is resized and recompressed to at most 6000 px and 10 MB, lowering the JPEG quality step by step until it fits. That way the limits of Cloudinary's free plan are respected without Santi having to think about it.
• Automatic translation: Santi writes in one language and, when he publishes, DeepL fills in the missing ones. Each language can be corrected by hand.
• Themes: created and deleted from the dashboard.
• Automatic cleanup: when the library opens, the Cloudinary photos no set uses anymore are deleted in the background.
• Settings: profile photo and password change.
• On the phone too: the dashboard fits the phone screen, and the sign-in form lets you show or hide the password.
• And an easter egg just for the admin: a corner to keep going strong. 💪

The library: each set is published or moved to draft with a switch.

The editor: photos on the left, texts per language and the translate button on the right.

⚡ Performance: measure, cut and measure again

I didn't leave performance for the end: I measured with Lighthouse, went after what weighed the most and measured again. This is how it looks today on desktop with a 4G network:

First round: from 44 to 73 on mobile

The first measurement, on October 15 on mobile with slow 4G (the most demanding case), gave a performance score of 44-48, with a CLS of 0.333 and an LCP of 7.5 s. Three changes fixed almost all of it:

• Preloading the home page's main photo from index.html, with fetchpriority="high". The preload script goes before any stylesheet, because a pending stylesheet blocks the scripts that come after it.
• The home page ships in the main bundle, without lazy loading, so there's no extra network round trip before the first page is painted.
• The footer is painted after the first navigation. It was responsible for all the CLS. The latest-set carousel also reserves its space while it loads.

Result on mobile: performance 73, CLS 0.001 and LCP 5.6 s.

Second round: removing what wasn't needed

• Self-hosted fonts. I serve them from the site's own domain, with no round trip to Google Fonts.
• Firebase out of the public pages. Reviewing the build, I saw that the Firebase bundle weighed 563 kB (168 kB compressed) and was preloaded on every page, and that every visit also opened a Google authentication iframe of about 93 KiB. All of that to read sets that are public. Now the public pages read Firestore with fetch against its REST API, with the same security rules.
• Login only loads when needed: a local flag says that an admin has already signed in on that browser. Visitors never download Firebase Auth. And the flag grants no permission: the real check is still Firebase.

Result on desktop with a 4G network: 100 in Performance, Accessibility, Best Practices and SEO.

What comes as standard

• Responsive images: every photo is served from Cloudinary with srcset in five widths (480, 800, 1200, 1600 and 2400 px) and automatic format and quality.
• Every page loads when it's visited (lazy loading), except the home page.

💡 The lesson: measure before optimizing. The biggest CLS problem was a footer, and the biggest weight, a library visitors didn't even use.

🛡️ Security

• Firestore rules that deny everything by default. The public can only read published sets, and settings only accept the allowed fields.
• Signed uploads: the browser never has permission to upload to Cloudinary on its own; every upload is signed by a function that first checks you're an admin.
• Contact form with length limits, escaped HTML and a trap field: bots fill it in, get an "OK" and nothing is sent.
• Staging isn't indexed: staging builds carry noindex and a robots.txt that disallows everything.

🧪 Quality: order isn't negotiable, the linter enforces it

When AI writes most of the code, conventions can't depend on someone remembering them. So I turned them into rules: if the code doesn't follow the order, lint fails, no matter who wrote it. The rules have been there since the first day of the project.

Five custom ESLint rules, written for this project:

The last two only warn, they don't reorder on their own: in interfaces, for example, moving members can break code that uses spread or Object.assign, so I'd rather a person decide.

And the rest of the order, also automatic:

• Imports grouped and sorted: Angular and external libraries first, then the internal aliases (@core, @features...) and the relative ones last.
• Object keys in alphabetical order in data, constants, models and interfaces.
• Translation JSON with sorted keys and no comments.
• Prettier with plugins that sort CSS properties, HTML attributes and JSON keys.
• Strict TypeScript: any is an error, return types are required and === is always used.

The dictionary pattern

There's one practice I always ask for that no linter enforces: the dictionary pattern, known in English as object lookup (and as a dispatch table when the values are functions). When a function maps one value to another, no switch and no chained if/else: an object typed with Record, key access and a default value with ??.

const TRANSLATE_ERRORS: Record<TranslationError['reason'], string> = {
  failed: 'admin.editor.translate.errors.failed',
  limit: 'admin.editor.translate.errors.limit',
  'not-allowed': 'admin.editor.translate.errors.notAllowed',
};

Three advantages:

• It reads at a glance: every case in one table, instead of spread across branches.
• TypeScript makes sure none is missing: with Record<TranslationError['reason'], string>, if a new error reason shows up tomorrow, the code won't compile until it has its text.
• Adding a case is adding a line, without touching the logic.

If instead of a value you need to run something, the values become functions: that's the dispatch table. There's a trap here that I had in my own notes:

const LOKI_DEFAULT_DISGUISE = 'Loki';

const LOKI_DISGUISES = {
  Hulk: () => 'Thanos',
  Thor: () => 'Odin',
};

// ❌ If the enemy isn't in the table: TypeError, ... is not a function
const disguise = LOKI_DISGUISES[enemy]() ? LOKI_DISGUISES[enemy]() : LOKI_DEFAULT_DISGUISE;

// ✅ With ?.() nothing runs if it doesn't exist, and ?? sets the default value
const disguise = LOKI_DISGUISES[enemy]?.() ?? LOKI_DEFAULT_DISGUISE;

Besides breaking on an unknown key, the first version runs the function twice. And ?? is better than the ternary: it only uses the default value when the key doesn't exist, not when the result is a valid '' or 0.

It isn't dogma: in templates I use @switch when each case renders something different, and there's still the odd switch where each branch does more than return a value.

And the tests:

• 857 cases in 117 files, with Vitest and JSDOM, the api/ functions included.
• Conventional commits validated by a script.

🐛 Five real problems (and how I solved them)

1. Tabs that broke after every deploy

A tab opened before a deploy asked for files from the previous build, which no longer existed. The pages that load when you visit them (gallery, About, the dashboard) wouldn't open and said nothing.

The fix was a navigation error handler that, if downloading a part of the app fails, reloads that page from scratch to get the new build. It only does it for download errors and once in a row per page, so a real outage can't cause a reload loop.

2. Taking Firebase off the public pages

The savings are covered in the performance section; the delicate part was security. I moved login into a store that loads on demand, and the local flag that decides when to load it grants nothing: if someone forges it, all they get is to download Firebase Auth, because the real check is still the login and the admin document in Firestore.

3. Vercel functions and ES modules

The api/ functions failed on Vercel: as native ES modules, relative imports need the .js extension. Besides the fix, I added a test that checks every import in api/ so it doesn't happen again.

4. A photo cleanup that can't get it wrong

Deleting "orphan" photos is easy; deleting only the orphans, not so much. The cleanup learned with each case:

• If it can't read the sets, it deletes nothing. A failed read doesn't mean no photos are in use.
• It only counts as deleted the photos Cloudinary confirms.
• It respects the profile photo and the ones in the admin's corner, which live in the same folder.
• It doesn't touch photos less than 7 days old and deletes at most 100 per run.

5. "Saving…" forever

When saving the profile photo on a slow connection, if the save took too long the app asked the server whether it had arrived... with no time limit for that question. Now that check has its own 5-second limit, and reading the session saved in IndexedDB gives up after 2 seconds, because some browsers never answer.

📅 Day by day

🎯 Lessons

1. Speed comes from the method, not just from AI. Written requirements, tests first, branches and review: without them, 75 commits in a day would be 75 problems.
2. Persistent memory changes the game. An agent that remembers decisions and bugs from previous sessions doesn't repeat them.
3. Verifying beats generating. Nothing reached production without passing tests, lint and build.
4. Free tiers go a long way if you design around their limits (Cloudinary, Firebase, DeepL Free, Resend and Vercel).
5. Security isn't delegated to the frontend. The Firestore rules and the functions that check for an admin are what protect it; the interface just goes along.

⭐ gentle-ai on GitHub: github.com/Gentleman-Programming/gentle-ai. If you find it useful, give it a star.

🎬 Introduction: the page loads, the video doesn't

My company-managed MacBook had worked flawlessly for four years with this setup: a USB-C hub (Ethernet, webcam and a VGA output to a TV) and an external monitor over HDMI whose audio I use, with the monitor's headphone jack feeding the TV speakers. Then one day YouTube stopped playing: the page loaded perfectly, but the video spun forever at 0:00.

This is what my desk looks like:

The pattern was what made it baffling. It happened at home, but not at my second home, which uses a different ISP. And a Linux PC on the same home network, with the same browser, worked fine. Everything pointed to the network or the ISP, combined with a company-managed Mac (MDM, a SASE secure-web-gateway client, a managed encrypted DNS profile and an endpoint security agent). Too many suspects.

💡 Spoiler: the network was innocent. But it took me hours to accept it, and the path is what's worth telling.

🤖 How I worked: iterating with agents

I didn't do this investigation alone. I worked in the terminal with AI coding agents (Claude Code) configured through gentle-ai, an open-source tool (official website) that configures the agents you already use with persistent memory, Organic-Driven Development, curated skills and sub-agent orchestration, with no agent lock-in.

What gentle-ai brought in this case:

• Engram: persistent memory across sessions, so you never start from scratch.
• ODD (Organic-Driven Development): a lightweight flow, with a task document for substantial work, a branch before writing and no commits without my explicit permission.
• Sub-agent orchestration: the orchestrator delegated writers that drafted this post in three languages and generated the diagrams; I reviewed and corrected.

gentle-ai was created by Alan Buscaglia (Gentleman Programming), and his rule for working with AI sums up this post well: "verifying beats generating".

⭐ gentle-ai on GitHub: github.com/Gentleman-Programming/gentle-ai. If you find it useful, give it a star: it helps more people find it.

The method was always the same, and we were both wrong at times: the agent also fell for wrong theories (the SASE client and ISP cache one was its own), and the evidence corrected it just as it corrected me.

hypothesis → test → evidence → discard

• 🤖 The agent: read system and network logs, inspected configuration, captured and decoded the player's traffic, launched headless Chrome through DevTools, built the playback monitor, ran the isolation tests and wrote the Swift watcher with its LaunchAgent.
• 🙋 Me: provided context and screenshots, ran the browser checks the agent couldn't and, above all, noticed it broke exactly when plugging in the USB-C hub and confirmed the setup had worked the same way for four years.

🕵️ False lead #1: the home DNS filter

First the obvious one: the Pi-hole at home. We ruled it out before really starting, with evidence: DNS resolved everything correctly and only ad domains were blocked. Nothing to do with the video servers.

🚦 False lead #2: QUIC / HTTP3

The classic "page loads, video doesn't": a firewall or ISP breaking QUIC. We disabled QUIC in the browser (brave://flags/#enable-quic) and the video still failed. Ruled out.

🧩 False lead #3: ad blockers and extensions

The console showed net::ERR_BLOCKED_BY_CLIENT errors for YouTube telemetry (qoe, log_event, generate_204). Very suspicious... until we tried a private window with shields off: telemetry went through and the video was still stuck. Those errors were noise.

🛡️ False lead #4: the SASE client

This was the most convincing one. The SASE client's network extension kept running even when I "disabled" it from its UI (tamper protection), and its logs, which the agent read, showed it handling browser flows to googlevideo.com. On top of that, my ISP served the video from a Google cache node inside its own network. The hypothesis, which was the agent's own, fit beautifully: traffic tunneled through the SASE cloud gets rejected by the ISP-embedded cache.

Three facts took it apart:

• The certificate the browser received was Google's genuine one: no TLS interception.
• The cache node answered fine (a proper 204).
• And decisively: Chrome doesn't go through that client at all (zero flows in its log) and failed identically.

👻 False lead #5: the "ghost" IPv6 route

Another AI assistant suggested an IPv6 problem. The agent checked, and then retracted the idea: the Mac had no global IPv6, the utun default routes were interface-scoped system tunnels, the browser's IPv6 attempt failed instantly and fell back to IPv4, and my home network has no IPv6 at all. Ruled out. Account and cookies weren't it either: a completely clean Chrome profile, with no cookies, no account and no extensions, stalled too.

🔬 The clue in plain sight

All along there was one observation that, in hindsight, pointed away from the network. YouTube's response was valid: a SABR/UMP stream of about 1 MB of real audio and video, with stream protection status OK. The bytes arrived fast. But the player never consumed them: video.readyState stayed at 0, buffered was empty and the player sat in state 3 (buffering).

"The data arrives but the player never starts." That is not a network problem.

🔁 The turn: making it reproducible

After a reboot it worked... and later it broke again. So I stopped guessing and asked the agent to build a monitor: every 2 minutes it launched a clean headless Chrome through the DevTools Protocol, loaded a video, checked readyState and currentTime, and snapshotted the system on every state change.

Then I noticed something, and this part was mine, not the agent's: it broke exactly when I plugged in the USB-C hub, on a setup I knew had worked the same way for four years. The agent ran an isolation test with the hub connected:

There it was. Without audio the video plays; with audio going to the HDMI monitor, it doesn't.

🎯 The root cause: a stuck audio device

Plugging the hub makes macOS reconfigure displays and audio devices, and the HDMI monitor's audio device ends up stuck, even though it never disappears from the device list. Chromium won't start playback until it can open the audio sink, so the video waits forever even though the data has already arrived.

Here is my setup, with the exact spot where it failed:

This also explains the rest of the mystery:

• 📍 "It only happens at home": that's where the hub and monitor setup lives. The network was a red herring; the correlation with place was really a correlation with hardware.
• ⏱️ "It breaks from time to time": the hub is a bit flaky and gets touched. Every re-plug triggers the problem again.

🔧 The manual fix

You just need to re-initialize the audio device. Three ways:

1. Open Audio MIDI Setup, select the HDMI device and change the format from 48,000 Hz to 44,100 Hz and back.
2. Switch the sound output to another device and back.
3. Restart the audio service: sudo killall coreaudiod.

A counter-test confirmed that the reset is what fixes it, not the sample rate: 48 kHz works again after a reset. Setting a fixed rate does not help, because macOS already remembers it per device.

🤖 The automated fix

Since the problem came back with every re-plug, I asked the agent to automate it, and it wrote a small Swift program that uses CoreAudio and runs as a per-user LaunchAgent; I reviewed and installed it. It listens for changes to kAudioHardwarePropertyDevices, waits 4 seconds for things to settle (debounce), and toggles the target device's nominal sample rate to another available rate and back. The first version never triggered, because the monitor never disappears from the device list; the agent fixed it to react to any change in that list.

🧾 The program (~/bin/hdmi-audio-reset.swift)

// Watches CoreAudio devices and re-initializes a given output device whenever the device
// list changes (e.g. after plugging a USB-C hub), by toggling its nominal sample rate.
// Works around the device getting stuck, which blocks Chromium media playback.
// usage: hdmi-audio-reset <deviceName> [--now]
import CoreAudio
import Foundation

let targetName = CommandLine.arguments.count > 1 ? CommandLine.arguments[1] : "VS278"
let settleSeconds: TimeInterval = 4

func log(_ message: String) {
  let line = "\(ISO8601DateFormatter().string(from: Date())) \(message)\n"
  FileHandle.standardError.write(line.data(using: .utf8)!)
}

func address(_ selector: AudioObjectPropertySelector) -> AudioObjectPropertyAddress {
  AudioObjectPropertyAddress(mSelector: selector, mScope: kAudioObjectPropertyScopeGlobal, mElement: kAudioObjectPropertyElementMain)
}

func deviceIDs() -> [AudioDeviceID] {
  var addr = address(kAudioHardwarePropertyDevices)
  var size: UInt32 = 0
  guard AudioObjectGetPropertyDataSize(AudioObjectID(kAudioObjectSystemObject), &addr, 0, nil, &size) == noErr else { return [] }
  var ids = [AudioDeviceID](repeating: 0, count: Int(size) / MemoryLayout<AudioDeviceID>.size)
  guard AudioObjectGetPropertyData(AudioObjectID(kAudioObjectSystemObject), &addr, 0, nil, &size, &ids) == noErr else { return [] }
  return ids
}

func name(of id: AudioDeviceID) -> String? {
  var addr = address(kAudioObjectPropertyName)
  var value: Unmanaged<CFString>?
  var size = UInt32(MemoryLayout<Unmanaged<CFString>?>.size)
  guard AudioObjectGetPropertyData(id, &addr, 0, nil, &size, &value) == noErr else { return nil }
  return value?.takeRetainedValue() as String?
}

func findTarget() -> AudioDeviceID? { deviceIDs().first { name(of: $0) == targetName } }

func sampleRate(of id: AudioDeviceID) -> Float64? {
  var addr = address(kAudioDevicePropertyNominalSampleRate)
  var rate: Float64 = 0
  var size = UInt32(MemoryLayout<Float64>.size)
  return AudioObjectGetPropertyData(id, &addr, 0, nil, &size, &rate) == noErr ? rate : nil
}

func availableRates(of id: AudioDeviceID) -> [Float64] {
  var addr = address(kAudioDevicePropertyAvailableNominalSampleRates)
  var size: UInt32 = 0
  guard AudioObjectGetPropertyDataSize(id, &addr, 0, nil, &size) == noErr else { return [] }
  var ranges = [AudioValueRange](repeating: AudioValueRange(), count: Int(size) / MemoryLayout<AudioValueRange>.size)
  guard AudioObjectGetPropertyData(id, &addr, 0, nil, &size, &ranges) == noErr else { return [] }
  return ranges.map { $0.mMinimum }
}

@discardableResult
func setSampleRate(_ id: AudioDeviceID, _ rate: Float64) -> OSStatus {
  var addr = address(kAudioDevicePropertyNominalSampleRate)
  var value = rate
  return AudioObjectSetPropertyData(id, &addr, 0, nil, UInt32(MemoryLayout<Float64>.size), &value)
}

func resetTarget() {
  guard let id = findTarget(), let current = sampleRate(of: id) else { log("\(targetName) not found; skipping"); return }
  guard let other = availableRates(of: id).first(where: { $0 != current }) else { log("no alternate rate for \(targetName)"); return }
  let first = setSampleRate(id, other)
  Thread.sleep(forTimeInterval: 1)
  let second = setSampleRate(id, current)
  log("reset \(targetName): \(Int(current)) -> \(Int(other)) -> \(Int(current)) (status \(first)/\(second))")
}

let wasPresent = findTarget() != nil
if CommandLine.arguments.contains("--now") { resetTarget(); exit(0) }
log("watching for \(targetName) (present=\(wasPresent))")
if wasPresent { DispatchQueue.main.asyncAfter(deadline: .now() + settleSeconds) { resetTarget() } }

// Any device-list change (hub plugged/unplugged, displays reconfigured) can leave the
// target stuck even though it never disappears, so reset it after changes settle.
var pendingReset: DispatchWorkItem?
var devicesAddr = address(kAudioHardwarePropertyDevices)
AudioObjectAddPropertyListenerBlock(AudioObjectID(kAudioObjectSystemObject), &devicesAddr, DispatchQueue.main) { _, _ in
  log("audio devices changed; resetting \(targetName) in \(Int(settleSeconds))s")
  pendingReset?.cancel()
  let work = DispatchWorkItem { resetTarget() }
  pendingReset = work
  DispatchQueue.main.asyncAfter(deadline: .now() + settleSeconds, execute: work)
}
dispatchMain()

📄 The LaunchAgent (~/Library/LaunchAgents/local.hdmi-audio-reset.plist)

Replace YOUR_USER with your user name and VS278 with the name of your audio device.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>local.hdmi-audio-reset</string>
  <key>ProgramArguments</key>
  <array><string>/Users/YOUR_USER/bin/hdmi-audio-reset</string><string>VS278</string></array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardErrorPath</key><string>/Users/YOUR_USER/Library/Logs/hdmi-audio-reset.log</string>
</dict>
</plist>

▶️ Compile and install

swiftc -O -o ~/bin/hdmi-audio-reset ~/bin/hdmi-audio-reset.swift
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/local.hdmi-audio-reset.plist

To uninstall:

launchctl bootout gui/$(id -u)/local.hdmi-audio-reset

I verified it end to end: I unplugged and replugged the hub, the log showed audio devices changed; resetting …, then the reset, and YouTube played without touching anything.

🧠 Lessons

• Rule out layers with evidence, not intuition. Every false lead was closed with a concrete test, not a hunch.
• Distrust the first plausible story. The agent and I chased the network for hours because the story fit too well (the SASE and ISP cache theory was the agent's own).
• "Data arrives but nothing plays" means look at the media pipeline (audio, decoder), not the network.
• Make the failure reproducible and automated. A monitor every 2 minutes gave me what intuition couldn't: the trigger.
• Change one variable at a time. The isolation test in the table above solved in minutes what hours of hypotheses couldn't.
• The correlation with place was really a correlation with a hardware setup.

I did the investigation iterating with AI agents in the terminal (Claude Code, configured with gentle-ai): they ran and organized the tests, and fell for wrong theories just like I did. This post was also drafted by sub-agents orchestrated by gentle-ai (the text in three languages and the illustrations), and I reviewed and corrected it. What moved us both forward was ruling things out with evidence.

If you have a Mac, a USB-C hub and HDMI audio, and YouTube sits at 0:00, try resetting the audio device first. It might save you a whole afternoon. 🎧

🌪️ Introduction: The Invisible Chaos of Spaces and Commas

In large-scale projects where multiple consultancies coexist, the diversity of criteria is not only a cultural richness — it is also a technical risk. A problem as silent as it is disruptive emerges: visual inconsistency. When each team brings its own development DNA — some preferring tabs, others spaces; single quotes versus double quotes — the repository ceases to be a cohesive asset and becomes a battlefield of irrelevant changes.

This lack of unification is not a mere aesthetic detail; it is a source of operational friction and vendor finger-pointing during code reviews. Discussions about brace placement or line length steal golden minutes that should be invested in architecture or business logic.

💡 For a technical leader, standardisation is not a whim: it is a strategy to eliminate noise and ensure that Code Reviews focus on what truly adds value.

✨ Ending Style Wars with Prettier

The solution to eradicate this friction is to delegate responsibility to Prettier. As an opinionated code formatter, Prettier eliminates subjectivity by parsing code and reprinting it under strict, predefined rules.

What makes it indispensable for a Software Architect is its safety: Prettier acts on the presentation layer without altering the Abstract Syntax Tree (AST). This provides a fundamental guarantee:

"The application's behaviour remains exactly the same"

Adopting Prettier is, in essence, an act of liberation for the team. By automating style, developers shed the cognitive load of visually "fitting in" with the rest, allowing Developer Experience (DevEx) to flow towards solving complex problems.

⚙️ Minimal configuration in .prettierrc

{
  "arrowParens": "always",
  "bracketSameLine": false,
  "printWidth": 100,
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5"
}

🕵️ The Git "Hack" to Format Without Losing the Trail

The greatest fear when implementing a standard on a live project is the mass commit. By formatting the entire codebase at once, we risk obscuring the original authorship. If a developer uses git blame to understand why a technical decision was made two years ago, they will find that the author is "the formatting bot", losing historical traceability.

To evolve the codebase without sacrificing this trail, we use the .git-blame-ignore-revs file.

🔍 How it works

1. You format the entire project and commit.
2. You obtain the hash of the formatting commit.
3. You register it in .git-blame-ignore-revs:

# Mass formatting commit with Prettier — 2024-10-15
a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

4. You configure Git to use it automatically:

git config blame.ignoreRevsFile .git-blame-ignore-revs

This functionality allows you to:

• 👤 Preserve original authorship: Git ignores that commit in traces.
• 🏛️ Maintain history integrity: GitHub and GitLab respect this file, showing the true author of the business logic.
• 🔇 Evolution without noise: Achieve visual perfection without "contaminating" the historical responsibility of each line.

🌐 Node.js as the Cross-Platform "Source of Truth"

In modern ecosystems, especially in Angular-based projects, operating system independence is critical. The classic mistake of many automations is relying on Bash scripts, which often fail in Windows environments or require tedious manual configuration.

Our architecture proposes a paradigm shift: treating the repository as an application environment rather than a system environment. By centralising everything in Node.js, we guarantee true cross-platform behaviour:

• 💻 Hardware agnosticism: The workflow works the same on a MacBook M3 as on a Windows 10 workstation.
• 🔒 Controlled environment: If the developer has Node.js installed (a requirement for Angular), the automation will work by default.
• 📦 Unified tooling: The package.json becomes the single source of truth.

🐶 Husky and lint-staged: The Silent Guardians of the Repository

For standardisation to be effective, it must be invisible and mandatory. We implement a forced compliance workflow using Husky and lint-staged, acting as a quality filter before code reaches the server:

1. 🚀 Trigger: The developer runs git commit.
2. 🪝 Interception: Husky captures the event and delegates execution to Node.js.
3. 🎯 Smart filtering: lint-staged identifies only the files in the Staging Area. No time is wasted processing thousands of static files — only what has changed.
4. ✅ Formatting and validation: Prettier applies the format. If the code has critical syntax errors, the commit is aborted.

📦 Installation

npm install --save-dev husky lint-staged
npx husky init

🔧 Configuration in package.json

{
  "lint-staged": {
    "*.{ts,html,scss,json,md}": ["prettier --write"]
  }
}

Pre-commit hook (.husky/pre-commit)

node_modules/.bin/lint-staged

🛡️ This process eliminates the human forgetfulness factor and guarantees that no non-standard code ever enters the repository, without the developer having to run a single additional command.

📋 Action Plan: Proof of Concept (POC)

As Architects, we do not implement critical changes blindly. The path to visual excellence follows a clear technical roadmap:

1. 🌿 Isolation: Create a feature/prettier-standardisation branch to avoid disrupting the current workflow.
2. ⚙️ Configuration: Install the stack (Prettier, Husky, lint-staged) and define the rules in .prettierrc.
3. 💥 Mass execution: Format the entire project and generate the reference commit.
4. 🛡️ History protection: Configure the .git-blame-ignore-revs file with the obtained hash.
5. 🎬 Live demo: Show the team and client how poorly indented code on Windows is instantly corrected on commit, preserving the original authorship in the history.

🚀 Conclusion: Towards a Culture of Clean Code

Adopting this ecosystem is not just a technical improvement; it is a declaration of principles about quality. The benefits are immediate: more agile code reviews, an impeccable Git history, and the complete elimination of aesthetic friction between consultancies.

The investment to implement this architecture is minimal compared to the long-term savings in time and frustration. At the end of the day, the question for any technology leader is simple:

How much time is your team wasting discussing the format of commas, when they could be strengthening the architecture of their system?

Automation is the bridge between visual chaos and technical excellence. And happy May the 4th, may the force be with you in every commit! 🌌⚔️