CLAUDE.md in this repository opened with this:

Colors: Terminal green (#55ff55), amber (#ff8855), cyan (#55ffff), magenta (#ff55ff) Typography: Monaco, Menlo, Ubuntu Mono - monospace fonts only Background: Pure black (#000000) with terminal gray text (#c9c9c9) No modern UI elements: No gradients, shadows, or contemporary web design patterns

The site it describes has not existed since episode 026, when I replaced the whole thing with Syne headings, Plus Jakarta Sans body text, and an emerald teal accent. The document sat there for months, confidently instructing anyone who read it — me, or any tool I pointed at the repo — to preserve an aesthetic that had already been deleted.

This is a post about auditing every Markdown file in a repo against the code, and what falls out when you do.

The failure mode: docs are asserted, code is executed

Code has a forcing function. Write something false in a .ts file and the build fails, the tests go red, the page renders wrong. Documentation has no such mechanism. A .md file that describes a system deleted a year ago will keep describing it forever, and nothing anywhere will complain.

Worse, docs are load-bearing for decisions. Nobody reads a stale file and shrugs; they read it and act. In this repo the stale design section was actively steering work in the wrong direction — every time I asked for a change, the instruction "maintain the strict 90s terminal aesthetic" came along for the ride.

The tell that finally caught it: I asked for a comparison against other developer portfolios, and the answer came back framed around preserving a terminal look. Then I actually opened the site. Light mode. Teal. Geometric sans. Nothing terminal about it.

What the audit found

Seven non-post Markdown files. Every one contained something false.

1. The design system in CLAUDE.md was a year out of date

Replaced with what the code actually says, sourced from tailwind.config.ts and src/index.css rather than memory:

/* src/index.css — the real accent */
--primary:      162 75% 38%;   /* light */
--primary-glow: 162 75% 52%;

// tailwind.config.ts — the real fonts
fontFamily: {
    sans:    ['Plus Jakarta Sans', 'sans-serif'],
    heading: ['Syne', 'sans-serif'],
}

2. BLOG.md documented a colour system that does nothing

An entire chapter explained how technical terms were automatically colour-coded as you wrote — React in yellow, Spring Boot in blue, Docker in green, with a table of mappings and instructions for adding your own terms.

Here is the function that was supposed to be doing it:

class SemanticColorizer {
    colorizeText(text) {
        return text;
    }
}

An identity function. It takes text and returns the same text. At some point the colouriser was gutted and the documentation was not.

The instructions for extending it were worse than useless — they told you to add entries to an autoColorTerms key in blog/config.json. That key does not exist in the file. You could follow the documentation exactly and produce no effect whatsoever, with no error to tell you why.

3. README.md had a CI pipeline that isn't there

It described a four-job workflow:

1. build-blog … 2. commit-blog … 3. build-portfolio … 4. deploy

The actual .github/workflows/deploy.yml has exactly one job, build-and-deploy, that does all four things in sequence. It also claimed Node v18 while package.json requires >=20.19.0, and advertised "semantic highlighting" — the identity function again.

4. plan.md was a finished roadmap with every box unticked

Ten - [ ] items for a thumbnail generator that has been shipping images for months. Its design spec also named Outfit and Inter as the site fonts and violet #7c3aed as "Site Primary" — two design systems ago.

I marked it complete and added a header noting which parts are superseded, but deliberately did not rewrite the body. It is a record of what was planned at the time. Rewriting it would erase the decision history, which is the only thing a finished roadmap is still good for.

5. The post template promised magic it can't do

blog/posts/_template.md — the file you copy to start writing — told you the build would colour your technical terms automatically. Every new post started from a lie about how the system works.

The part I did not change

There are 35 blog posts in this repo. Many describe the terminal aesthetic. Several walk through the colour system in detail. All of them are now, strictly speaking, inaccurate about the current site.

I left every one of them alone.

A blog post is a dated record of what was true when it was written. Episode 026 is the redesign — rewriting the posts around it to match today's CSS would falsify the very history the blog exists to keep. Documentation describes the present tense and must track it; posts describe a moment and must not.

The distinction is worth being explicit about, because "update all the docs" could easily be read as "update all the Markdown," and those are very different instructions. The test I used: would changing this file make a past statement untrue? If yes, it is a record — annotate it, don't edit it. If no, it is documentation — fix it.

Then: 60 lines of configuration nobody reads

Documenting blog/config.json accurately required knowing which keys the build actually uses. Rather than assume, I checked each one:

for k in semanticCategories contextualRules tagColors colors social resumeUrl baseUrl; do
  grep -c "config\.$k" blog/scripts/build.js blog/templates/*.html
done

The results split cleanly:

semanticCategories alone was ~60 lines: six categories, each with a description and a list of twenty-odd patterns mapping words like kubernetes, microservices and memory leak to colour roles. Carefully structured, clearly the product of real thought, and read by absolutely nothing.

Config that looks tunable but has no effect is worse than no config. It is a trap for your future self: something renders wrong, you find a promising-looking pattern list, you edit it, you rebuild, nothing changes, and now you are debugging the wrong file.

Deleting it safely

The claim "this config is dead" is falsifiable, so I tested it rather than trusting the grep. Build the site with the original config, hash the output. Build with the trimmed config, hash again:

local build, ORIGINAL config: 24c885867cd00cd5080264df6c0982a0
local build, TRIMMED config:  24c885867cd00cd5080264df6c0982a0

Byte-identical. blog/config.json went from 134 lines to 51, and every remaining key is live.

One wrinkle worth recording: the freshly built sitemap.xml did differ from the committed one — but the same diff appeared with the original config too, and the sorted URL sets hashed identically. It was ordering that differs between my machine and the CI runner, not an effect of the deletion. Without the A/B test I might have blamed my own change and reverted a correct edit.

What I added to stop the drift

Fixing the docs does not stop them rotting again. Two things now push back:

A precedence rule, written into CLAUDE.md itself:

This repo has repeatedly shipped documentation that outlived the code — the terminal aesthetic, the semantic colour system, a "24 posts" roadmap. When a doc and the code disagree, the code wins. Check src/index.css, tailwind.config.ts, blog/scripts/build.js and .github/workflows/deploy.yml before acting on any description in a Markdown file.

A document instructing you not to trust it is a strange artefact, but it is honest about the failure mode, and it names the files that hold ground truth.

An explicit dead-code section, so the identity-function colouriser is documented as broken rather than quietly omitted. Silence reads as "fine". Naming it means the next person either fixes it or deletes it, instead of rediscovering it in a year.

Lessons

Docs rot silently; code rots loudly. Nothing in CI checks that CLAUDE.md matches index.css. Until something does, assume every Markdown file is stale until verified against source.

Verify before documenting. The most useful output of this audit was not the prose — it was the grep -c that proved four config keys were dead. I would never have found that by reading, only by checking.

Distinguish records from documentation. Blog posts, ADRs, finished roadmaps are dated artefacts: annotate, never rewrite. READMEs, agent instructions, templates are present-tense: they must track reality or actively mislead.

Dead configuration is a liability, not neutral weight. Sixty lines that look meaningful and do nothing will cost someone an afternoon. Delete it, and prove it was dead with a byte-comparison rather than an argument.

Fix the template. _template.md is copied into every new post. A false statement there propagates into everything you write next — the highest-leverage line in the repository, and the easiest to forget.

Repo: jeffreyjose07/spring-validation-lab
Stack: Java 21, Spring Boot 4.1, Gradle 9.3, H2, JUnit

This post is the series index. The short overview was not enough — the detailed write-ups live in the posts below.

Deep dives

Teaching notes in the repo mirror the same path under docs/. Folklore corrections live in docs/ground-truth.md.

The loop

1. State the production trap.
2. Write the broken service on purpose.
3. Assert the failure (wrong rows, NPE, timeouts, pool fully checked out).
4. Write the fixed design.
5. Assert the success.
6. Write down every place Boot 4.1 disagreed with the blog-post version of Spring.

How to try it

git clone https://github.com/jeffreyjose07/spring-validation-lab.git
cd spring-validation-lab
export JAVA_HOME=$(/usr/libexec/java_home -v 21)   # macOS
./gradlew test --tests '*SelfInvocationProxyTest'

Open a single test in IntelliJ and watch the Run console for LabLog banners like:

========== [PHASE1-PROXY] BROKEN self-invocation ==========
  → Calling this.saveIndependently(...) — REQUIRES_NEW sticky note will NOT be read

What I am not doing next (yet)

I am deliberately not racing into Kafka outbox / saga posts until the Phase 1–2 proofs feel boring. The point of this lab is competence under the hood, not checklist coverage.

If you interview for Spring-heavy backend roles: stop only reading about proxies. Make one fail on purpose. Keep the green and red tests. Write down every place the framework surprised you.

This post: proxies and @Transactional self-invocation.
Next: ThreadLocals and @Async.

I used to say “self-invocation bypasses the proxy” in interviews like it was a slogan. That is not the same as being able to force a rollback and point at a row count of zero. This post is the full proof we built for that trap — theory, broken code, fixed code, assertions, and the ground-truth surprise that still trips people in follow-ups.

The production trap

You need an audit (or ledger) write that must survive even if the outer business method fails and rolls back. The textbook move is @Transactional(propagation = Propagation.REQUIRES_NEW) on an “independent” method.

Someone writes:

@Transactional
public void processBatchThenFail(...) {
    this.saveIndependently(accountId, amount); // looks fine
    throw new IllegalStateException("boom");
}

@Transactional(propagation = Propagation.REQUIRES_NEW)
public void saveIndependently(...) {
    repository.save(...);
}

In production review this often ships. In a real outage it looks like “REQUIRES_NEW is broken.” It is not. The call never crossed a Spring AOP proxy, so the sticky note was never read.

Theory: sticky notes, not JVM keywords

@Transactional is not bytecode magic by default. Spring wraps your bean in a CGLIB (or JDK) proxy when transaction AOP is active. External callers receive the proxy from the ApplicationContext.

Call path that works:

1. Caller → proxy
2. Proxy sees @Transactional → begins / suspends / joins a transaction
3. Proxy invokes your real method on the target
4. Proxy commits or rolls back on the way out

Call path that fails silently:

1. You are already inside the target method
2. You call this.saveIndependently(...)
3. this is the raw target object, not the proxy
4. No interceptor runs → REQUIRES_NEW is dead text
5. The “independent” save joins (or shares) the outer transaction
6. Outer throw → everything rolls back together

REQUIRES_NEW means: suspend the outer TX and open a new one. That only happens if the proxy sees the call.

Ground truth you should say in interviews

Inside a method body, this is never the proxy — even when a transaction is already active because the proxy opened it.

People say: “If TransactionSynchronizationManager.isActualTransactionActive() is true, then AopUtils.isAopProxy(this) must be true.” We measured the opposite.

Proof of interception is one of:

• TransactionSynchronizationManager.isActualTransactionActive() after entering via a proxied call
• Checking the bean injected from the context (AopUtils.isAopProxy(injectedBean) == true)
• Observing commit/rollback behavior under controlled failure (best)

Never trust AopUtils.isAopProxy(this) inside the class as proof that annotations are “on.”

Broken design (lab)

Class: BrokenSelfInvocationLedgerService

@Transactional
public void processBatchThenFail(String accountId, long amount) {
    this.saveIndependently(accountId, amount);
    throw new IllegalStateException("Simulated business failure after independent save");
}

@Transactional(propagation = Propagation.REQUIRES_NEW)
public void saveIndependently(String accountId, long amount) {
    repository.save(new LedgerEntry(accountId, amount));
}

Console banners (via LabLog) make the intent loud while the test runs:

========== [PHASE1-PROXY] BROKEN self-invocation ==========
  → Calling this.saveIndependently(...) — REQUIRES_NEW sticky note will NOT be read
  ✗ Throwing after 'independent' save — expect BOTH to roll back...

How we proved it

Test: SelfInvocationProxyTest#selfInvocationDoesNotCommitIndependently

./gradlew test --tests '*SelfInvocationProxyTest.selfInvocation*'

Assert:

1. Method throws IllegalStateException (simulated business failure).
2. repository.countByAccountId("acct-broken") is 0.

If REQUIRES_NEW had fired, the independent row would already be committed before the outer throw. Zero rows means there was only one transaction, and it rolled back.

That is the interview-grade proof: not a stack trace story, a persisted count.

Fixed design (lab)

Split the independent write onto another Spring bean so the call crosses a proxy boundary.

• FixedLedgerService — outer @Transactional, orchestrates, then throws
• IndependentLedgerWriteService — @Transactional(REQUIRES_NEW) + repository save

@Transactional
public void processBatchThenFail(String accountId, long amount) {
    independentWriteService.saveIndependently(accountId, amount);
    throw new IllegalStateException("Simulated business failure after independent save");
}

Same failure throw. Different call graph.

How we proved the fix

Test: SelfInvocationProxyTest#separateBeanRequiresNewSurvivesOuterRollback

Assert:

1. Outer method still throws.
2. repository.countByAccountId("acct-fixed") is 1.

The independent TX committed before the outer rollback. That is the behavioral definition of REQUIRES_NEW working.

Why “inject self” is a weaker fix

You can inject your own bean and call self.saveIndependently(...). It works mechanically. It also keeps two concerns in one class and confuses readers (“why is this calling itself through a field?”).

Prefer:

• A small dedicated write service (what the lab does), or
• An application event / outbox later when the independence is really a domain boundary

For interviews: know that self-injection works; prefer a separate bean as the clean answer.

What this teaches beyond the slogan

1. Annotations are metadata. Without an interceptor (proxy, AspectJ weave, etc.), they do nothing.
2. Propagation only applies at proxy boundaries. REQUIRED, REQUIRES_NEW, NESTED — same rule.
3. Silent failure is the danger. Self-invocation does not throw “annotation ignored.” It just behaves like a normal method call.
4. Prove with data. Rollback + row count beats hand-waving about AOP.

Interview answers that hold under follow-up

Q: Why did my REQUIRES_NEW audit roll back with the payment?
A: Likely called via this. The proxy never saw the call. Split the write onto another bean and re-test with an intentional outer failure; the audit row should remain.

Q: How do you know you are talking to a proxy?
A: The object from the context is a proxy when AOP applies. Inside the method, this is still the target. Use TX activity / commit behavior, not isAopProxy(this).

Q: Does @EnableAspectJAutoProxy(exposeProxy = true) + AopContext.currentProxy() count?
A: Yes, it can force re-entry through the proxy. It is a smell for most codebases — couples you to AOP internals. Prefer another bean.

How to run just this proof

git clone https://github.com/jeffreyjose07/spring-validation-lab.git
cd spring-validation-lab
export JAVA_HOME=$(/usr/libexec/java_home -v 21)   # macOS
./gradlew test --tests '*SelfInvocationProxyTest'

Teaching notes: docs/01-proxies-and-transactions.md
Ground-truth notes: docs/ground-truth.md

One-liner

Annotations like @Transactional only apply when the call crosses a Spring proxy. Self-invocation is a silent no-op for AOP.

Next: Spring ThreadLocals and @Async — where SecurityContext goes when work jumps threads, and why “null SecurityContext” is usually the wrong diagnosis.

Previous: Proxies and self-invocation
This post: ThreadLocals, @Async, and SecurityContext
Next: Bean lifecycle and mini-umbrellas

The classic interview line is: “@Async loses the SecurityContext because ThreadLocal does not cross threads.” That sentence is directionally right and operationally sloppy. On Spring Boot 4.1 we had to be precise — and we had to build a naive executor on purpose, because the default path did not fail the way folklore promised.

The production trap

Request thread authenticates the user. Controller calls a service that fires @Async audit logging. The worker thread calls:

SecurityContextHolder.getContext().getAuthentication().getName();

Boom: NPE. Ops blames “null SecurityContext.” Debug session shows something more annoying: getContext() returned a non-null empty context. What was null was Authentication.

Same class of bug shows up with:

• raw Executor / CompletableFuture.runAsync
• parallelStream() after reading ThreadLocal state
• custom thread pools without a TaskDecorator

Theory: lockers, not magic globals

SecurityContextHolder uses a strategy. Default strategy is ThreadLocal (MODE_THREADLOCAL). Think of it as a labeled locker on the current thread:

1. Filter / interceptor puts Authentication into the context on the Tomcat (or WebFlux — different story) thread.
2. Your service reads it on that same thread — fine.
3. @Async schedules work on a pool thread — different locker.
4. Unless something copied the context onto the worker, the worker’s locker is empty.

Fixes fall into two buckets:

Explicit is clearer for audits and batch jobs. Framework propagation is convenient when many layers already assume SecurityContextHolder.

Ground truth: folklore vs Boot 4.1

1. Default @Async may already propagate

Folklore: Any @Async method always sees a missing security context.

Lab: Plain @Async on our Boot 4.1 / modern Spring Security stack did not reliably demonstrate the failure. Framework wiring already helped in some paths.

So the lab defines naiveAsyncExecutor — a ThreadPoolTaskExecutor with no TaskDecorator — and binds the broken service with @Async("naiveAsyncExecutor"). That keeps the ThreadLocal loss demonstrable and honest.

Interview phrasing: ThreadLocal does not cross threads unless the executor (or Security) copies it. Always verify your executor bean.

2. Empty context ≠ null context

SecurityContextHolder.getContext() typically returns a context object even when nobody is authenticated. The failure mode is almost always:

context != null
authentication == null
authentication.getName() → NPE

Say that out loud in interviews. It signals you have actually tripped the bug.

Broken design (lab)

BrokenAsyncAuditService:

@Async("naiveAsyncExecutor")
public CompletableFuture<String> logAccessBroken() {
    Authentication auth = SecurityContextHolder.getContext().getAuthentication();
    if (auth == null) {
        return CompletableFuture.failedFuture(
                new NullPointerException("SecurityContext is null on async thread"));
    }
    return CompletableFuture.completedFuture(auth.getName());
}

(The error message says “SecurityContext” for historical slogan reasons; the check is on Authentication. The test asserts the NPE cause.)

AsyncConfig#naiveAsyncExecutor — no decorator, no copy, no clear.

How we proved it

Test: SecurityContextAsyncTest#asyncWithoutPropagationLosesSecurityContext

./gradlew test --tests '*SecurityContextAsyncTest.asyncWithout*'

Setup: put UsernamePasswordAuthenticationToken("jeffrey", ...) on the test thread.

Assert: join() fails with CompletionException whose cause is NullPointerException (missing auth on worker).

Fixed design A — explicit argument

ExplicitAsyncAuditService takes String username (or could take a richer DTO). The worker never reads SecurityContextHolder for identity.

Test: explicitArgumentPropagationWorks → result equals "jeffrey".

This is the design I push hardest in interviews for fire-and-forget audit: make the boundary obvious. Arguments are visible in signatures, logs, and tests.

Fixed design B — framework copy

PropagatingAsyncAuditService uses @Async("securityContextPropagatingExecutor").

The executor sets:

executor.setTaskDecorator(runnable -> {
    SecurityContext context = SecurityContextHolder.getContext();
    return new DelegatingSecurityContextRunnable(runnable, context);
});

DelegatingSecurityContextRunnable installs the captured context on the worker thread before run(), then restores/clears appropriately so the next task on that pool thread does not inherit yesterday’s principal.

Test: frameworkPropagationWorks → worker still sees "jeffrey" with no explicit arg.

Why clear matters

Without cleanup, pool threads keep ThreadLocals. User A’s request finishes; thread returns to pool; User B’s task briefly sees User A. That is a security incident class, not a style nit.

What we learned that slides skip

1. ThreadLocal is a concurrency primitive, not a request-scoped DI feature. Crossing threads is always your problem unless the framework documents a copy.
2. @Async is not one behavior. It depends on which Executor bean is wired and whether Security auto-config decorated it.
3. Prefer explicit data for domain events. Propagation is for when you must keep calling SecurityContextHolder deep in shared libraries.
4. Prove both failure and fix. One green “async works” test teaches nothing about the failure mode.

Interview answers that hold

Q: Why did async audit log as anonymous / NPE?
A: Worker thread did not receive Authentication. Context object can still be non-null. Check the executor for a Security TaskDecorator, or pass the principal explicitly.

Q: Is SecurityContextHolder.setStrategyName(MODE_INHERITABLETHREADLOCAL) the fix?
A: It helps only for child threads created in ways that inherit ThreadLocals. It is easy to misuse with pools (inheritance at pool-thread creation time ≠ per-task copy). Prefer decorator or explicit args for @Async pools.

Q: What about WebFlux / reactive?
A: Different model (Reactor Context), not ThreadLocal-by-default the same way. Do not answer a servlet @Async question with Reactor slogans.

How to run just this proof

./gradlew test --tests '*SecurityContextAsyncTest'

Docs: docs/02-threadlocals-and-async.md

One-liner

ThreadLocal state does not cross thread boundaries. @Async, parallelStream, and raw thread pools leave Authentication behind unless you copy it or pass data explicitly — and verify your executor, because modern defaults may already propagate.

Next: Bean lifecycle, circular dependencies, and repository mini-umbrellas.

Previous: ThreadLocals and @Async
This post: lifecycle, circular dependencies, repository mini-transactions
Next: HikariCP, connection hogging, optimistic locking

Phase 1 is not only proxies and ThreadLocals. Three related traps show up in every senior Spring loop: startup seeding that “has @Transactional but doesn’t,” circular constructor graphs that refuse to boot, and services that throw after two save() calls only to discover both rows persisted because there was never an outer umbrella.

We proved all three with H2.

Trap 1 — @PostConstruct before the proxy

Theory (lifecycle order, simplified)

1. Instantiation (new)
2. Injection (constructors / setters / fields)
3. Initialization (@PostConstruct, InitializingBean, …)
4. AOP proxy creation / publish bean to the context for clients

So when @PostConstruct runs, you are still on the raw target. A @Transactional sticky note on that method is unread. No Spring transaction umbrella opens from that annotation.

People then observe: “but my seed rows are in the DB!” Correct — Spring Data repository methods are themselves @Transactional(REQUIRED). With no outer TX, each save() opens a mini-transaction, commits, and returns. Your PostConstruct “transaction” failed; the repository’s did not.

Broken-ish design we measured

PostConstructSeeder:

@PostConstruct
@Transactional // ignored — no proxy yet
public void seedOnStartup() {
    observedAsProxyDuringPostConstruct = AopUtils.isAopProxy(this);
    transactionActiveDuringPostConstruct =
            TransactionSynchronizationManager.isActualTransactionActive();

    repository.save(new SeedConfig("MAX_USERS", "5000"));
    repository.save(new SeedConfig("THEME", "DARK"));
}

How we proved it

Test: PostConstructBeforeProxyTest

./gradlew test --tests '*PostConstructBeforeProxyTest'

Assert during PostConstruct observations:

Second test in the same class: after full context build, the injected PostConstructSeeder is a proxy (AopUtils.isAopProxy(postConstructSeeder) == true). An ApplicationRunner (AfterContextReadySeeder) with @Transactional sees txActive=true and can seed under a real umbrella.

What to do instead

For transactional startup work, wait until the context is ready:

• ApplicationRunner / CommandLineRunner
• ContextRefreshedEvent listener
• explicit @Transactional service called from those hooks (so the call crosses a proxy)

Do not put critical multi-step transactional seeding on @PostConstruct.

Trap 2 — constructor circular dependencies

Theory

Constructor injection A ↔ B means neither object can finish construction without the other. There is no half-built instance to stash in the third-level cache the way field/setter injection historically allowed.

Spring Boot disables circular references by default since 2.6. Field injection cycles also fail unless you re-enable the escape hatch. The principled fix is almost always a third orchestrator or @Lazy on one side — not “turn circular refs back on and move on.”

How we proved the crash

ConstructorCircularDependencyTest uses ApplicationContextRunner scanning profile-gated circular beans.

1. Constructor cycle (circular-constructor profile) → context hasFailed, cause mentions circular / BeanCurrentlyInCreationException.
2. Field cycle (circular-field) → also fails by default on modern Boot.
3. Runner escape hatch: .withAllowCircularReferences(true) boots the field cycle.
4. Principal fix: @Lazy on one constructor parameter boots cleanly without enabling circular refs globally.

./gradlew test --tests '*ConstructorCircularDependencyTest'

Ground truth: the property people mis-cite

Folklore: set spring.main.allow-circular-references=true and every test harness suddenly allows cycles.

Lab: that property applies to SpringApplication. A raw ApplicationContextRunner ignores it. Use:

runner.withAllowCircularReferences(true)

or fix the graph with @Lazy / redesign.

If an interviewer asks “how do you allow circular references in tests?”, distinguishing SpringApplication vs ApplicationContextRunner is a strong senior signal.

Trap 3 — repository mini-umbrellas

Theory

SimpleJpaRepository methods are @Transactional with Propagation.REQUIRED:

• Outer TX present → join it
• No outer TX → open a short-lived transaction, commit on method exit

So “my service method is not transactional” does not mean “nothing commits until I say so.” It means each repository call may commit immediately.

That is catastrophic for multi-step writes that must be atomic: save A, save B, throw → both A and B already durable.

Broken design (lab)

NonTransactionalNoteService — no class/method @Transactional, two save()s, then throw.

Fixed / contrasting design

TransactionalNoteService — outer @Transactional, same two saves, then throw → both roll back.

How we proved it

Test: RepositoryMiniUmbrellaTest

./gradlew test --tests '*RepositoryMiniUmbrellaTest'

Same throw. Different atomicity. The difference is the umbrella.

How the three traps connect

All three are about when Spring’s transactional interceptors exist and who opens the transaction:

Once you see that map, “transactional seeding on PostConstruct” and “partial commits without outer TX” stop feeling like unrelated trivia.

Interview answers that hold

Q: Can I use @Transactional on @PostConstruct?
A: The annotation on that method is ignored; proxy does not exist yet. Rows may still persist via repository mini-transactions. Use a runner after context refresh.

Q: Why did half my writes survive an exception?
A: No outer transaction. Each Spring Data save likely committed independently. Wrap the unit of work in @Transactional on a proxied service method.

Q: Constructor circular dependency — enable the flag?
A: Prefer redesign or @Lazy. Know Boot defaults to deny cycles. Know spring.main.allow-circular-references is a SpringApplication concern; runners need their own API.

How to run Phase 1 lifecycle proofs

./gradlew test --tests '*PostConstructBeforeProxyTest'
./gradlew test --tests '*ConstructorCircularDependencyTest'
./gradlew test --tests '*RepositoryMiniUmbrellaTest'

Docs: docs/03-bean-lifecycle.md

One-liner

Know the lifecycle order. Startup transactional work needs a fully built context. And “no outer transaction” does not mean “no transaction” — repositories will invent mini ones.

Next (Phase 2): HikariCP exhaustion, connection hogging, and optimistic locking.

Previous: Bean lifecycle and mini-umbrellas
This post: Phase 2 — pools, hogging, optimistic locking

Phase 1 was about whether Spring’s sticky notes fire. Phase 2 is about what happens when they fire too well under load: every transaction wants a scarce Hikari connection, nested REQUIRES_NEW wants a second one, slow HTTP keeps the first one checked out, and twenty buyers fight over one unit of stock.

We proved three failure modes on Java 21 / Spring Boot 4.1 with a deliberately tiny pool (max 10) and H2.

Shared ground truth: connections are often lazy

Folklore: entering @Transactional always checks out a Hikari connection immediately.

Lab: with JPA, the connection is often acquired on first SQL. Pure CPU / HTTP at the start of a transactional method may hold 0 connections until the first query/flush. Hogging and pool math should be reasoned from “first SQL,” not from method entry alone.

Say that in interviews. It changes how you narrate connection-hog timelines.

Trap 1 — REQUIRES_NEW vs pool size

Theory

Normal @Transactional (REQUIRED): one connection for the TX duration (once acquired).

REQUIRES_NEW on a nested bean: suspend outer TX, open a new TX → typically needs a second connection while the parent still holds the first.

Bad schedule with maximumPoolSize = 10:

1. Ten threads enter parent TX
2. Each runs first SQL → each holds 1 connection → pool empty
3. Each calls nested REQUIRES_NEW → needs connection #11…#20
4. Hikari checkout timeouts / cascade failures

This is not “Hikari is broken.” It is synchronous nested transactions under a saturated pool.

Lab design

• PaymentWithRequiresNewAuditService — parent @Transactional, saveAndFlush (acquire conn), optional barrier, then nested call
• NestedRequiresNewAuditService — @Transactional(REQUIRES_NEW) audit write

Ground truth: H2 is too fast without a barrier

Folklore: 10 threads × REQUIRES_NEW always deadlocks a pool of 10.

Lab: on H2, SQL is so fast that some parents finish before all ten hold a connection. The “deadlock window” never opens. We force the bad schedule with a CountDownLatch:

auditLogRepository.saveAndFlush(...); // hold parent connection
allParentsHolding.countDown();
allParentsHolding.await(...);         // wait until pool is full
nestedRequiresNewAuditService.writeIndependentAudit(paymentId);

Production latency (real DB, GC, network) makes the bad schedule easier to hit “naturally.” Tests must manufacture it.

How we proved it

Test: RequiresNewPoolExhaustionTest

./gradlew test --tests '*RequiresNewPoolExhaustionTest'

Assert: with 10 concurrent callers and the barrier, ≥ 5 fail getting the second connection (we allow races but demand real pain; a perfect 10/10 deadlock is ideal but not required for the lesson).

What to do instead

• Prefer async audit / outbox over synchronous REQUIRES_NEW under load
• If you must nest, size the pool for parents + nested worst case — and admit that cost
• Do not stack REQUIRES_NEW in hot request paths as a default “make it durable” hammer

Trap 2 — connection hogging (HTTP inside the TX)

Theory

Admin bulk price update:

1. For each SKU, call manufacturer HTTP (slow)
2. Read/update product row
3. All inside one @Transactional

After the first SQL, Hikari connection stays checked out for the rest of the method — including every subsequent vendor round-trip. Ten parallel admins → pool empty → login / checkout die even though the DB is idle.

Broken design (lab)

BrokenBulkPriceUpdateService:

@Transactional
public void processBulkUpload(List<PriceChange> changes) {
    for (PriceChange change : changes) {
        if (vendorClient.verifyWithManufacturer(change)) { // slow, inside TX
            Product product = productRepository.findBySku(...); // acquires/holds conn
            product.setPrice(change.newPrice());
            toUpdate.add(product);
        }
    }
    productRepository.saveAll(toUpdate);
}

Fixed design (lab)

FixedBulkPriceUpdateService — no @Transactional on the orchestrator:

1. Do all vendor HTTP first (0 DB connections)
2. Call DbBatchPriceService.batchUpdatePrices(valid) — short @Transactional batch

Network work outside the umbrella. DB work in a tight proxy call.

How we proved it

Test: ConnectionHoggingTest

./gradlew test --tests '*ConnectionHoggingTest'

Assert roughly:

Watch LabLog banners: PHASE2-HOG broken vs fixed.

Interview nuance

If someone says “never do HTTP in a transaction,” refine it: never do HTTP while holding a DB connection. With lazy acquisition, HTTP before first SQL inside @Transactional is still a bad habit (long TX, lock duration later) but it is not the same as pool starvation. After first SQL, it is pool starvation.

Trap 3 — optimistic locking under flash traffic

Theory

One VIP SKU, stock = 1, twenty concurrent buyers. Pessimistic SELECT … FOR UPDATE serializes and holds row locks. Optimistic @Version:

1. Each TX reads version = N
2. Winner flushes UPDATE … SET stock=0, version=N+1 WHERE id=? AND version=N → 1 row updated
3. Losers’ UPDATE matches 0 rows → Hibernate StaleStateException → Spring often wraps as ObjectOptimisticLockingFailureException

Fast fail. No long lock waits. Callers retry or show “sold out.”

Lab design

@Entity
public class InventoryItem {
    // ...
    @Version
    private Integer version;
}

InventoryPurchaseService.purchaseOne:

• read by SKU
• if stock < 1 → IllegalStateException("Out of stock")
• decrement, saveAndFlush
• rethrow optimistic failures after logging

Ground truth: exception names

Logs may show Hibernate StaleStateException / batch failures before Spring’s ObjectOptimisticLockingFailureException. Same concept. Name both if probed.

How we proved it

Test: OptimisticLockingTest

./gradlew test --tests '*OptimisticLockingTest'

Seed: one IPHONE-VIP with stock 1. Fire 20 threads.

Assert:

That last assert matters: we proved the version collision path, not only “later threads saw stock 0.”

How Phase 2 fits Principal-level answers

Senior answers list tools. Principal answers connect resource budgets:

• Connections are a hard cap (pool size)
• Every open TX after first SQL is a checked-out connection
• Nested TX multiplies demand
• Remote I/O multiplies hold time
• Contention strategy (@Version vs locks) is a product decision under flash sales

The lab makes those sentences falsifiable.

How to run Phase 2

./gradlew test --tests '*RequiresNewPoolExhaustionTest'
./gradlew test --tests '*ConnectionHoggingTest'
./gradlew test --tests '*OptimisticLockingTest'

Docs: docs/04-connection-pools-and-locking.md
Ground truth: docs/ground-truth.md

One-liner

Never hold a DB connection across remote I/O. Never stack synchronous REQUIRES_NEW under a saturated pool. Prefer optimistic locking when collisions are rare or you need fail-fast under flash traffic.

That closes Phase 1–2 of the lab. I am deliberately not racing into Kafka outbox / saga write-ups until these proofs feel boring. If you interview Spring-heavy backend roles: clone the repo, run one red test and one green test, and keep your own ground-truth file for every place Boot 4 disagreed with the slide deck.

Dependabot and merge order

Five frontend-related bumps landed after resolving conflicts:

• Headless UI → 2.2.9
• axios → 1.12.2
• @hookform/resolvers → 5.2.2
• react-hook-form → 7.65.0
• React 19 with aligned types

Headless UI went in before React 19 on purpose. Older Headless UI majors and React 19 do not always play nice together; ordering the merge avoids a broken peer dependency surface while the lockfile settles.

After React 19 landed, useRef typing in search-related components needed tightening—straightforward breakage from stricter generics, fixed in place rather than suppressed with any.

Health checks and abuse resistance

Nothing changed about what “healthy” means: the deep route still aggregates real dependencies. The hardening story is who can hammer it and how often the expensive path runs.

Security configuration allows anonymous access to actuator-style health probes where uptime tools need them: /api/actuator/health/** and /actuator/health/** (see commit 13580ca on the app repo). That keeps external monitors and container health checks honest without opening the rest of the admin surface.

To avoid turning /api/health/status into an accidental DDoS against your own databases:

• TTL caching on the deep health response so repeat hits within a window reuse a stored result.
• A separate rate-limit bucket for health traffic so normal API throttles stay sensible.
• Broader URL patterns on the limiting filter (/api/*, /actuator/*, /health) so probes and API traffic are categorized consistently.

Configuration lives under app.health.* (cache TTL and related knobs in application.yml). Tests cover the health controller—including cache behavior—so regressions fail in CI instead of production.

Render, Docker, and the frontend install step

Render’s Docker build failed during frontendInstall: Testing Library React v13 and React 19 do not belong in the same install graph. The fix was to move to @testing-library/react v16, add @testing-library/dom, bump @testing-library/user-event, and regenerate package-lock.json so CI and Docker see one consistent tree.

GitHub Actions: one place for scheduled pings

The app repository now owns .github/workflows/ping-app-health.yml: cron roughly every five minutes plus workflow_dispatch, APP_BASE_URL secret, curl, and jq for a readable summary. That is where scheduled wake-ups belong—same repo as the service, secret colocated with deployment docs.

Earlier I had experimented with a portfolio workflow (keep-alive.yml) hitting the Render URL from jeffreyjose07.github.io. That duplicated the cron and split configuration across projects. I removed it from the Pages repo so there is exactly one scheduler: the chat platform workflow. No duplicate pings, no need for APP_BASE_URL on the blog side.

What I deliberately did not commit

Local backend/src/main/resources/static/static/js/main.* bundles from a dev build stayed out of git—noise, not source of truth.

Links and commits (app repo)

• 13580ca — actuator health paths reachable for anonymous probes.
• f04579c — ping workflow, Testing Library / lockfile fix, health cache, rate limits, tests, and config.

If you fork the platform, copy the ping workflow and set APP_BASE_URL in that repository’s secrets; keep the portfolio repository focused on static site and blog builds only.

Running a proper design audit against current frontend trends changed that. Quickly.

What the Audit Found

The first thing that jumped out was something I'd describe as a split personality problem. The Hero, Projects, and Contact sections used my Tailwind CSS custom property system — bg-background, text-primary, glass-card — everything properly tokenized. But Skills and Experience were hardcoding raw utility classes: bg-gray-800, text-gray-600, bg-blue-600. They came from a different project, and it showed. Scrolling through the portfolio felt like visiting two different websites stapled together.

The second issue was more embarrassing: two animations were completely broken. The floating blobs in the Hero used animate-float, and Skills/Experience used animate-slide-up. Neither keyframe was defined in tailwind.config.ts. They just silently failed — the elements appeared without animation, and I'd never noticed because the degradation was invisible.

Third: all animations fired on page load, not when sections entered the viewport. Elements deep in the page had already "animated" before a user could possibly see them. The effect was wasted.

And then there was the elephant in the room: electric violet everywhere, paired with Inter and Outfit. The same purple-gradient-on-dark combo that's on roughly every developer portfolio generated in the last two years. Not a good look when you're trying to stand out.

Fixing the Foundation

I started with the quick wins. Added the missing float and slide-up keyframes to tailwind.config.ts. Also slowed the hero's pulsing mesh animation from 4 seconds to 8 — at 4s it was subtly nauseating on long page dwell.

For scroll-triggered animations, I wrote a small useInView hook using the browser's native IntersectionObserver API. Each section now carries a ref, and animations only trigger when the element crosses the viewport threshold. The hook disconnects the observer after the first trigger — no repeated firing, no React render loops.

export function useInView(threshold = 0.15) {
  const ref = useRef<HTMLElement>(null);
  const [isInView, setIsInView] = useState(false);

  useEffect(() => {
    const el = ref.current;
    if (!el) return;
    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          setIsInView(true);
          observer.unobserve(el);
        }
      },
      { threshold }
    );
    observer.observe(el);
    return () => observer.disconnect();
  }, [threshold]);

  return { ref, isInView };
}

Twenty-five lines. No library needed.

The Color System

I replaced the violet primary — hsl(263 70% 50%) — with emerald teal at hsl(162 75% 38%). The choice wasn't arbitrary. Teal at that lightness sits in a useful spot: dark enough to pass WCAG AA contrast on white backgrounds, vivid enough to glow against dark ones. The companion gradient goes teal-to-cyan, which has a directional warmth that violet-to-purple lacks.

The gradient text on the name now reads white-to-teal in dark mode, and teal-to-cyan in light mode. The mesh background radials, the glow border effect, the section dividers — all updated to match. It's a surprisingly large surface area when you start counting.

Typography

Swapped Inter for Plus Jakarta Sans as the body font, and Outfit for Syne as the heading font. Syne is wide and geometric at heavy weights — it brings a kind of confident authority that Outfit's roundness doesn't. Plus Jakarta Sans has more character than Inter while staying clean enough for long-form reading. Both are available on Google Fonts and load with the same preconnect strategy.

The pairing feels more deliberate. Less off-the-shelf.

Skills and Experience: Proper Redesigns

The Skills section got torn down and rebuilt. The old version was a flat badge cloud inside gray cards — every skill had identical visual weight, so Kubernetes sat next to Unit Testing as equals. That's not how expertise actually works.

The new layout has two tiers. Signature expertise — Spring Boot & WebFlux, Apache Kafka, Microservices Architecture, Kubernetes & GCP, PostgreSQL & MongoDB, Reactive Programming — displayed as larger bordered cards with category tags. Below that, a full toolkit organized by domain (Languages, Data, DevOps, Architecture, Quality). Recruiters scanning in six seconds see the differentiators first.

Experience got a more significant transformation. The old stacked card layout was a direct CV-to-web translation — readable, but forgettable. I replaced it with a vertical timeline: a connector line runs down the left side on desktop, with timeline dots marking each role, dates on a perpendicular axis, and entries that stagger-animate in on scroll. The career arc becomes visually legible at a glance.

The Smaller Fixes

A few things that don't make headlines but matter:

The Contact section had three hardcoded text-white labels for Email, Phone, and Location. They worked in dark mode. In light mode, white text on a near-white background — invisible. Fixed to text-muted-foreground.

The Hero subtitle was vague: "Code craftsman • Tech explorer • Minimalist". Pretty, but says nothing about what I actually do. Changed to "Senior Backend Engineer • Distributed Systems • 6 yrs @ Jio". Concrete. Scannable.

The academic projects section had its heading in text-muted-foreground — visually de-emphasized to the point of looking apologetic. Given these are worth showing, gave them a proper gradient heading treatment.

And the footer now closes with a small monospace line: > crafted with care, deployed with confidence. A nod to the terminal aesthetic of the blog.

Reflecting on Design Complacency

The honest thing to admit is that most of these issues weren't introduced all at once. They accumulated — a section copied from somewhere, a color variable updated in one place but not another, an animation added without checking the keyframe existed. Design debt works exactly like technical debt: it's quiet until you look directly at it.

Running an explicit audit forced the looking. The portfolio is sharper for it.

All changes are live. The build is clean, the animations fire when they should, and the violet is gone.

the pagination problem

Initially, the blog's pagination was simple but brittle. The build script generated flat HTML files like page2.html and page3.html. While functional, this approach had significant downsides:

1. URL Structure: jeffreyjose07.is-a.dev/blog/page2.html is not clean or idiomatic. The standard convention is a directory-based structure like /blog/page/2/.
2. Scalability: Flat files clutter the root directory and make URL management cumbersome.
3. SEO: Search engines prefer structured, predictable URL hierarchies.

the solution: directory-based routing

I refactored the Node.js build script (blog/scripts/build.js) to generate a nested directory structure. Instead of writing page${i}.html, the script now creates a directory for each page:

// Old approach
// fs.writeFileSync(path.join(OUTPUT_DIR, `page${i + 1}.html`), html);

// New approach
const pageDir = path.join(OUTPUT_DIR, 'page', (i + 1).toString());
if (!fs.existsSync(pageDir)) {
    fs.mkdirSync(pageDir, { recursive: true });
}
fs.writeFileSync(path.join(pageDir, 'index.html'), html);

This simple change transforms the URL from /blog/page2.html to /blog/page/2/, which is cleaner, professional, and more SEO-friendly. I also updated the pagination links in the template to respect this new structure:

<!-- Before -->
<a href="/blog/page2.html">2</a>

<!-- After -->
<a href="/blog/page/2/">2</a>

optimizing core web vitals

A recent PageSpeed Insights analysis revealed a mobile performance score of 91, which is good, but I aimed for perfection. The primary bottlenecks were Largest Contentful Paint (LCP) and Cumulative Layout Shift (CLS) caused by unoptimized images.

from background-image to img tags

The blog index originally displayed post thumbnails using div elements with background-image. While this makes it easy to handle different aspect ratios using background-size: cover, it has a major performance drawback: browser preloaders cannot discover background images as easily as <img> tags, delaying the LCP.

I refactored the template to use semantic <img> tags with modern CSS:

.post-thumbnail img {
    width: 100%;
    height: 100%;
    object-fit: cover; /* Replicates background-size: cover */
    transition: transform 0.5s ease;
}

intelligent loading strategy

To further improve LCP, I implemented a conditional loading strategy. The browser shouldn't lazy-load images that are in the initial viewport, nor should it eagerly load images that are off-screen.

I updated the build script to apply loading="eager" to the first 3 posts on the first page, and loading="lazy" to everything else. Additionally, for the main profile image on the homepage, I added fetchPriority="high" to explicitly signal its importance to the browser's resource scheduler.

// Eager load images for the first 3 posts on the first page, lazy load others
const loadingAttr = (i === 0 && index < 3) ? 'eager' : 'lazy';

thumbnailHtml = `<div class="post-thumbnail">
    <img src="${thumbSrc}" alt="${post.title}" loading="${loadingAttr}" width="400" height="225">
</div>`;

This ensures the most critical content loads immediately, while conserving bandwidth for the rest.

optimizing font delivery

In a second round of optimization, PageSpeed Insights still flagged Google Fonts as a render-blocking resource. To address this, I switched to a non-blocking loading strategy using rel="preload" combined with an onload handler.

<link rel="preload" as="style" href="..." />
<link rel="stylesheet" href="..." media="print" onload="this.media='all'" />
<noscript>
  <link rel="stylesheet" href="..." />
</noscript>

This technique allows the browser to fetch the font stylesheet asynchronously without blocking the initial paint, significantly improving the First Contentful Paint (FCP) metric.

accessibility wins

Performance isn't just about speed; it's about usability. The audit flagged several accessibility issues that needed immediate attention:

1. Icon-Only Buttons: Social media links and the theme toggle button lacked text labels, making them invisible to screen readers. I added aria-label attributes to all icon-only interactions.

   jsx

   <a 
     href={social.href} 
     aria-label={social.label} // Added for accessibility
     target="_blank"
   >
     <social.icon />
   </a>

2. Contrast Ratios: The "Email", "Phone", and "Location" labels in the contact section used a muted color that failed contrast guidelines on dark backgrounds. I updated the text color from text-zinc-400 to text-white to ensure maximum legibility for all users.

3. Heading Hierarchy: I restructured the heading levels in the Skills and Education sections (changing CardTitle to render as h3 and adjusting nested headings) to ensure a strictly sequential descending order, which is crucial for screen reader navigation.

4. Layout Stability: I added explicit width and height attributes to the main profile avatar. This allows the browser to reserve space for the image before it loads, preventing jarring layout shifts (CLS).

conclusion

These changes might seem small individually, but collectively they represent a significant step forward in engineering quality. By refactoring the pagination, we now have a robust URL structure. By optimizing images, we've reduced the LCP and improved the mobile experience. And by fixing accessibility issues, we've ensured the site is inclusive for everyone.

The journey of optimization is never truly finished, but today's updates bring us much closer to that 100/100 score.

Instead of manually designing a cover image for every new post in Figma or Canva, I did what any engineer would do: I wrote a script to do it for me.

The Goal

I wanted thumbnails that looked like a terminal window executing a command related to the post. For example:

• A backend post might show a curl request.
• A personal post might show a cat journal.md command.
• A database post might show a psql query.

The result needed to be a high-quality PNG that could be used as an Open Graph image (for Twitter/LinkedIn cards) and as the header image on the blog itself.

The Tech Stack

• Node.js: The runtime for the script.
• Puppeteer: A headless Chrome Node.js API. This is the secret sauce. It allows me to render HTML/CSS exactly as a browser would and take a screenshot.
• HTML/CSS: To design the "terminal window" layout.

The Implementation

1. The Template

First, I created an HTML template (template.html) that defines the look of the terminal. It uses Flexbox to center a "window" div, and CSS to style the window controls (the red, yellow, and green dots) and the dark background.

I used Google Fonts to load JetBrains Mono for the terminal text and Outfit for the window title, ensuring typography matches the rest of my site.

<div class="terminal-window">
    <div class="window-header">
        <div class="window-controls">
            <!-- Mac-style dots -->
            <div class="control-dot red"></div>
            <div class="control-dot yellow"></div>
            <div class="control-dot green"></div>
        </div>
        <div class="window-title">~/blog/posts/{{windowTitle}}</div>
    </div>
    <div class="terminal-content">
        {{terminalContent}}
    </div>
</div>

2. The Generator Script

The script (generate.js) reads my blog's configuration and post metadata. It then launches a headless browser instance using Puppeteer.

For each post, it:

1. Determines the "primary tag" (e.g., backend, personal, frontend).
2. Selects a corresponding "command pattern" based on that tag.
3. Injects the post title and the generated command into the HTML template.
4. Takes a screenshot of the rendered page.
5. Saves the image to public/assets/thumbnails/.

Here's a snippet of the logic that maps tags to terminal commands:

switch (primaryCategory) {
    case 'backend':
        commandHtml = `curl -X POST /api/v1/deploy`;
        outputHtml = `{"status": "success", "message": "Deployment initiated..."}`;
        break;
    case 'personal':
        commandHtml = `cat ~/journal/${slug}.md`;
        outputHtml = `Reflecting on: "${description}"`;
        break;
    // ... other categories
}

3. Build Integration

The best part is that this is now part of my build pipeline. Whenever I run npm run build:blog, the script checks if a thumbnail exists for each post. If it's missing, it automatically generates a fresh one in milliseconds.

This means I never have to worry about assets again. I just write the markdown, tag it appropriately, and the system generates a beautiful, custom thumbnail that perfectly matches the content.

The Result

You're looking at it right now! The thumbnail for this post was generated by the very system it describes. It's a meta-example of automation serving creativity.

By treating design assets as code, I've ensured 100% consistency across the blog while removing manual toil from my writing process.

1. Fixing the "Blank Screen" Issue

The Problem: Users were reporting that the blog content wasn't loading immediately, often resulting in a blank screen. This was caused by a "loading overlay" and a complex materialization animation that was intended to be a cool effect but ended up blocking content delivery.

The Solution: I decided to prioritize performance and immediate content visibility. I completely removed the loadingOverlay HTML element and its associated CSS animations and JavaScript logic. Now, the blog content renders instantly upon page load, providing a much snappier experience.

2. Collapsible Tag Filters

The Problem: As the number of tags grew, the "filter by tag" section on the homepage became cluttered and took up too much vertical space, pushing the actual blog posts down.

The Solution: I implemented a collapsible tag filter section.

• Default State: The section is now compact (limited to 85px height) by default.
• Interactivity: A "show more" button allows users to expand the full list of tags if they wish to explore.
• Auto-Expansion: If you navigate to the blog with a specific tag selected (e.g., via a URL hash), the section automatically expands to show the active tag.

3. Debugging Critical Interactivity Bugs

The Problem: After implementing the collapsible tags, I encountered a frustrating issue where the "show more" button and the tag filters themselves were completely non-functional. The browser console was surprisingly quiet, showing no obvious errors.

The Debugging Process:

1. Initial Investigation: I suspected the event listeners weren't attaching correctly. I tried moving the script placement and using DOMContentLoaded, but the issue persisted.
2. Deep Dive: I added extensive console.log statements, but none of them appeared. This suggested the script wasn't executing at all.
3. The Breakthrough: I inspected the generated HTML and found a syntax error in the injected data. The build script was replacing {{ allPostsData }} with the JSON data, but the regex was too strict and didn't account for the spaces I had added in the template for readability ({{ allPostsData }}). This resulted in invalid JavaScript syntax, crashing the entire script block.

The Fix: I updated the build script's regex to be more flexible:

.replace(/{{\s*allPostsData\s*}}/g, JSON.stringify(sortedPosts))

This simple change ensured the data was injected correctly, restoring all interactivity.

4. Restoring Animations and Sound

With the critical bugs squashed, I was able to re-enable the retro animations (like the "digital rain" effect) and the subtle sound effects that give this blog its unique cyberpunk aesthetic.

Conclusion

These updates highlight the importance of balancing aesthetic features with core usability. While animations are fun, they should never come at the cost of content accessibility. And sometimes, the trickiest bugs are hidden in the simplest places—like a few extra spaces in a template placeholder.

Today, I embarked on a mission to unify the branding and navigation across the entire jeffreyjose07.github.io ecosystem. Here's how I did it.

The "JJ" Monogram

The first step was to refine the logo. I wanted something bold, geometric, and instantly recognizable. The previous iteration was a bit too subtle.

I iterated on a design featuring two thick, rounded J's. To add a bit of dynamism, I made the left 'J' start slightly higher than the right one, and added a distinct dot on the right side. This created a balanced yet energetic monogram that works perfectly as a favicon and a header logo.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
  <defs>
    <linearGradient id="grad" x1="0%" y1="0%" x2="100%" y2="100%">
      <stop offset="0%" style="stop-color:#7c3aed;stop-opacity:1" />
      <stop offset="100%" style="stop-color:#3b82f6;stop-opacity:1" />
    </linearGradient>
  </defs>
  <!-- Left J -->
  <path d="M180 120 V340 A60 60 0 0 1 60 340" 
        fill="none" stroke="url(#grad)" stroke-width="80" stroke-linecap="round" />
  <!-- Right J -->
  <path d="M332 172 V340 A60 60 0 0 1 212 340" 
        fill="none" stroke="url(#grad)" stroke-width="80" stroke-linecap="round" />
  <!-- Dot -->
  <circle cx="420" cy="340" r="40" fill="url(#grad)" />
</svg>

With the new SVG in hand, I regenerated all the favicons—ICO, PNGs, and the Apple Touch Icon—ensuring that the site looks sharp on every device, from a 4K monitor to an iPhone home screen.

Unifying the Navigation

The biggest challenge was the navigation. My portfolio used a sleek "Top Bar" style, but the blog was still using an older "Floating Pill" design. Worse, the blog had a bug where duplicate menus would sometimes appear.

The "Top Bar" Standard

I decided to standardize on the "Top Bar" design. It's clean, professional, and provides easy access to all sections of the site without intruding on the content.

I updated src/components/Navigation.tsx to solidify this style for the main React app. Then, I turned my attention to the static parts of the site.

Fixing the Blog

The blog is statically generated using a custom Node.js script. I had to dive into blog/templates/header.html and completely rewrite the CSS and HTML to match the React component.

Key Changes:

1. Fixed Positioning: Moved from top: 1.5rem to top: 0 with width: 100%.
2. Backdrop Filter: Added a blur effect that activates on scroll, giving it that premium glassmorphism look.
3. Responsive Design: Ensured the mobile menu works seamlessly with the new layout.

Updating the Games

My games—Snake and Void Blocks—are standalone HTML pages. They also needed to join the family. I updated their headers to include the new logo and the standard Top Bar navigation. Now, whether you're playing a game, reading a blog post, or checking out my projects, the navigation remains consistent.

The Result

The result is a cohesive, polished experience. The new logo pops, the navigation feels familiar no matter where you are, and the site feels more like a single, unified product rather than a collection of disparate pages.

It's a small detail, but in UI/UX, details are everything.

Check out the new logo in the header above!