<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/">
  <channel>
    <title>KashhCMD Journal</title>
    <description>Technical articles on algorithms, performance and architecture</description>
    <link>https://kashcmdd.github.io/portfolio/</link>
    <atom:link href="https://kashcmdd.github.io/portfolio/rss.xml" rel="self" type="application/rss+xml" />
    <language>en-us</language>
    <lastBuildDate>Sat, 14 Nov 2026 20:12:19 GMT</lastBuildDate>
    <managingEditor>kashcmdd@users.noreply.github.com (KashhCMD)</managingEditor>
    <webMaster>kashcmdd@users.noreply.github.com (KashhCMD)</webMaster>
    <item>
      <title>Your Ladder Needs to Forget</title>
      <link>https://kashcmdd.github.io/portfolio/journal/elo-decay/</link>
      <guid isPermaLink="true">https://kashcmdd.github.io/portfolio/journal/elo-decay/</guid>
      <description>Rating decay is the least interesting part of a ranked system to build, and the easiest thing to get wrong.</description>
      <pubDate>Fri, 25 Sep 2026 00:00:00 GMT</pubDate>
      <category>ALGORITHMS</category>
      <content:encoded><![CDATA[<p>Every ranked ladder eventually develops a aristocracy. A handful of players grind the ladder for a season, hit the top rank, and then log off for a year. They are still at the top of the board, not because they are the best players on the server right now, but because nobody has taken their place. Newcomers are measured against a benchmark that stopped being true months ago.</p>
<p>The fix is decay: a background job that quietly reduces the rating of anyone who has not played within a cutoff window. It is about forty lines of code. Almost every interesting decision in it is about how much to remove and where to stop.</p>
<h3>Decaying to zero is the wrong answer</h3>
<p>The naive implementation subtracts a fixed amount per day of inactivity until the player hits the bottom of the scale. It works, and it is too harsh. A Diamond who has not logged in for two months should not wake up to Bronze, because the punishment massively exceeds the offence and almost every affected player quits rather than grinding their way back.</p>
<p>So the decay has a floor, and the floor is not zero. It is the rating at the bottom of whatever rank the player currently holds. They slide down through the tiers of their own band and stop, keeping the rank they earned. You only lose ground to people who are actually showing up.</p>
<pre><code class="language-python">min_elo = 0
for name, threshold, _ in reversed(RANKS):
    if r.elo &gt;= threshold:
        min_elo = threshold
        break

new_elo = max(r.elo - decay, min_elo)</code></pre>
<h3>Linear, and capped</h3>
<p>Decay is linear in days inactive, not exponential. A player away for a year should not be punished as if they had been away for three, so the total removed is clamped by a max_decay setting.</p>
<pre><code class="language-python">days_inactive = (datetime.now(timezone.utc) - r.last_active).days
decay = min(days_inactive * settings.decay_per_day, settings.max_decay)</code></pre>
<p>The query also filters on player_id being non-null. Ratings that are not linked to an actual player never decay, because a team-only or unattributed rating drifting downward on a timer is a bug that looks like a feature until someone notices their team rating fell for no reason.</p>
<h3>Auditing the machine</h3>
<p>The part I care about most: decay writes an audit log entry attributed to a system actor, exactly as if an administrator had made the change by hand. A rating that moves without a human touching it should be as traceable as one that did, and when a player disputes their rank six months later, that log row is the answer.</p>
<pre><code class="language-python">db.add(AuditLog(
    admin_id=&quot;system&quot;,
    admin_name=&quot;System&quot;,
    action=&quot;elo_decay&quot;,
    target_id=str(r.player_id) if r.player_id else None,
    details=f&quot;Decayed {actual_decay} ELO after {days_inactive} days inactive&quot;,
))</code></pre>
<h3>Scheduling it without shooting yourself</h3>
<p>APScheduler runs the job once a day inside the FastAPI lifespan. Two of its options are doing real work here and are easy to miss:</p>
<ul><li>max_instances=1 stops a slow run from overlapping the next one. Decay touches every stale rating in a single transaction, and two concurrent runs will fight over the same rows.</li><li>misfire_grace_time=3600 lets the job still run after a deploy or a crash, as long as it is within the hour. Otherwise every restart silently skips a day of decay.</li></ul>
<p>The whole job body is wrapped in a bare except that logs and swallows. A decay run that throws should not take the web app down with it, and it should leave a trace that says exactly which run failed.</p>
<h3>The part that is easy to forget</h3>
<p>Top positions on the leaderboard are exclusive: there is a first, a second, a third. Decay reshuffles the top of the table, which means the position numbers are now wrong for everyone above the highest decayed player. The job finishes by recalculating top positions and committing again. Without that step the board shows stale placements, and it will look like a data integrity bug rather than a missing recalculation.</p>]]></content:encoded>
    </item>
    <item>
      <title>Cutting 59% Off My Portfolio&#39;s JavaScript</title>
      <link>https://kashcmdd.github.io/portfolio/journal/bundle-splitting/</link>
      <guid isPermaLink="true">https://kashcmdd.github.io/portfolio/journal/bundle-splitting/</guid>
      <description>One static import was costing more than React, the router and every icon combined.</description>
      <pubDate>Fri, 25 Sep 2026 00:00:00 GMT</pubDate>
      <category>PERFORMANCE</category>
      <content:encoded><![CDATA[<p>The build was telling me something I had been ignoring: a single chunk over 500 kB, and a warning that nobody was going to read but me. The bundle was 1,076 kB raw, 340 kB gzipped, shipped as one file to every visitor. I went looking for what was actually in there instead of guessing.</p>
<p>The answer was hls.js. One dependency, 594 kB raw and 185 kB gzipped, imported at the top of a component that draws video backgrounds. It was the single largest thing on the site by a wide margin, and it was never needed for most of the page.</p>
<h3>It was already behind an IntersectionObserver</h3>
<p>The video background component only initialises playback once its container comes within 200px of the viewport. The lazy behaviour was already written. What was missing was that the parser itself was being downloaded up front, before any of that logic got a chance to run.</p>
<pre><code class="language-tsx">import type HlsType from &#39;hls.js&#39;;

// ...inside the effect, which only runs once the container is visible
const { default: Hls } = await import(&#39;hls.js&#39;);</code></pre>
<p>Because the observer gate already existed, the change was small: turn the static import into a dynamic one inside the effect, keep a type-only import for the variable so TypeScript still knows what hls is, and guard against the component unmounting while the chunk is in flight. The 594 kB now arrives when a video background actually scrolls into view, and not before.</p>
<h3>Safari does not need the parser at all</h3>
<p>HLS is a format Safari plays natively. Loading 594 kB of JavaScript to hand the browser a URL it can already handle is pure waste, so the native check happens before the dynamic import, not after it.</p>
<pre><code class="language-tsx">if (video.canPlayType(&#39;application/vnd.apple.mpegurl&#39;) &amp;&amp; hlsSource) {
  video.src = hlsSource;
  video.play().catch(() =&gt; {});
  return;
}</code></pre>
<h3>Splitting the rest</h3>
<p>With hls out of the way, the remainder was still a single 470 kB file. Splitting the vendors into named chunks does not reduce the total number of bytes anyone downloads, but it means React, the animation library and the icon set are cached independently of your app code. Shipping a one-line copy change no longer invalidates a megabyte of vendor JavaScript in everyone&#39;s browser.</p>
<pre><code class="language-ts">build: {
  rollupOptions: {
    output: {
      manualChunks(id) {
        if (!id.includes(&#39;node_modules&#39;)) return;
        if (id.includes(&#39;hls.js&#39;)) return &#39;hls&#39;;
        if (id.includes(&#39;gsap&#39;)) return &#39;gsap&#39;;
        if (id.includes(&#39;framer-motion&#39;) || id.includes(&#39;node_modules/motion&#39;))
          return &#39;motion&#39;;
        if (id.includes(&#39;lucide-react&#39;)) return &#39;icons&#39;;
        if (
          id.includes(&#39;node_modules/react/&#39;) ||
          id.includes(&#39;node_modules/react-dom/&#39;) ||
          id.includes(&#39;node_modules/scheduler/&#39;)
        )
          return &#39;react&#39;;
      },
    },
  },
}</code></pre>
<h3>Verifying it actually happened</h3>
<p>A bundle size table is easy to fool yourself with, so the check is in the built HTML. If the lazy chunk is still listed as a modulepreload, the browser is fetching it eagerly regardless of what the code says, and none of this mattered.</p>
<pre><code class="language-html">&lt;link rel=&quot;modulepreload&quot; href=&quot;/portfolio/assets/react-DGj8QgOs.js&quot;&gt;
&lt;link rel=&quot;modulepreload&quot; href=&quot;/portfolio/assets/motion-BA6OqAxL.js&quot;&gt;
&lt;link rel=&quot;modulepreload&quot; href=&quot;/portfolio/assets/icons-C8CewcuE.js&quot;&gt;
&lt;link rel=&quot;modulepreload&quot; href=&quot;/portfolio/assets/gsap-CzGW6FVa.js&quot;&gt;
&lt;!-- no hls --&gt;</code></pre>
<blockquote><p>Initial JavaScript went from 1,076 kB to about 440 kB. The hls chunk is still 595 kB, it just is not your problem until you scroll to it.</p></blockquote>
<p>Those figures are from the day of the change, and the site has grown a lot since: the journal, the command palette, the case-study modals, the decision log and the architecture diagrams all landed afterwards. First paint measures about 585 kB today, still spread across the same five cached chunks. That is not the exercise failing. Splitting was never a promise that the number would stay small, only that a growing one keeps arriving in pieces the browser can cache separately.</p>]]></content:encoded>
    </item>
    <item>
      <title>SQLite Is Fine Until It Isn&#39;t</title>
      <link>https://kashcmdd.github.io/portfolio/journal/sqlite-postgres/</link>
      <guid isPermaLink="true">https://kashcmdd.github.io/portfolio/journal/sqlite-postgres/</guid>
      <description>Two of my projects use the same data, in two completely different databases, for two completely different reasons.</description>
      <pubDate>Fri, 25 Sep 2026 00:00:00 GMT</pubDate>
      <category>ARCHITECTURE</category>
      <content:encoded><![CDATA[<p>ScriptForge stores its users, scripts and version history in a single SQLite file through better-sqlite3. Rainbow Leaderboard runs Postgres 16 through an async driver. Same person, same week, opposite decisions, and neither one is wrong.</p>
<h3>What ScriptForge gets from a file</h3>
<p>ScriptForge is a single Node process serving one deployment. Its entire dataset is a file on a disk. There is no replication to configure, no connection pool to size, nothing to administer at three in the morning, and the whole database can be backed up by copying one file. For a single-node deployment that is not a compromise, it is the correct choice.</p>
<pre><code class="language-bash">DATABASE_PATH=./data.sqlite</code></pre>
<p>better-sqlite3 is also synchronous, which in a Next.js route handler is simply convenient. There is no connection pool to leak and no await on the query path.</p>
<h3>Where the ceiling is</h3>
<p>SQLite serialises writes. That is the whole trade. It is invisible until you have concurrent writers, and then it appears as lock contention rather than as a database error, which makes it harder to diagnose. My own note in that repository says it plainly:</p>
<blockquote><p>SQLite is fine for a single-node hobby deployment; move lib/db.ts queries to Postgres before you expect concurrency.</p><footer>— ScriptForge README</footer></blockquote>
<h3>What forced Postgres</h3>
<p>Rainbow Leaderboard has scheduled work. A daily decay job walks every stale rating, writes an audit row for each one, recalculates exclusive top positions, and commits twice. Meanwhile the leaderboard, player profile and stats endpoints are all being read. That is concurrent writers against readers, and it is the exact workload SQLite is worst at.</p>
<pre><code class="language-python">DATABASE_URL=postgresql+asyncpg://rainbow:rainbow@db:5432/rainbow</code></pre>
<p>Postgres also gives the schema changes a home. Alembic versions every migration, so a scheduled job and a running server can never disagree about what the rating table looks like. SQLite would have needed that discipline maintained by hand.</p>
<h3>The actual lesson</h3>
<p>The mistake is treating this as a preference. A file-backed database and a client-server database are different tools, and the honest version of the README line above is the one I would write if I were starting again: pick SQLite while you have exactly one writer and no scheduled jobs, and migrate before you add either. Both of these projects are the same person, and the difference between them is the workload, not taste.</p>]]></content:encoded>
    </item>
    <item>
      <title>No Router, No Server, No 404</title>
      <link>https://kashcmdd.github.io/portfolio/journal/base-paths/</link>
      <guid isPermaLink="true">https://kashcmdd.github.io/portfolio/journal/base-paths/</guid>
      <description>This site lives under a subpath on GitHub Pages, which turns every URL question into a build-time one.</description>
      <pubDate>Fri, 25 Sep 2026 00:00:00 GMT</pubDate>
      <category>DEPLOYMENT</category>
      <content:encoded><![CDATA[<p>I ship this site to GitHub Pages, so it does not live at the root of a domain. It lives at /portfolio/. That one directory in front changes how every absolute URL in the project behaves, and the resolution happens at build time rather than at runtime, which means a URL can be perfectly correct on your machine and still 404 in production.</p>
<h3>One line decides where the site lives</h3>
<pre><code class="language-ts">base: &#39;/portfolio/&#39;,</code></pre>
<p>Everything downstream is a consequence of it. Asset imports, script tags and stylesheet links get the prefix applied automatically, so those were never a problem. The interesting failures come from paths Vite does not obviously own.</p>
<h3>Hand-written paths are not rewritten for you</h3>
<p>I self-host the fonts, and the @font-face rules live in a CSS file I wrote by hand. They referenced the files with a plain root-relative url, which resolves against the domain root:</p>
<pre><code class="language-css">src: url(&#39;/fonts/inter-normal-latin.woff2&#39;) format(&#39;woff2&#39;);</code></pre>
<p>Point that at localhost and it resolves. Point it at kashcmdd.github.io and it resolves to kashcmdd.github.io/fonts/inter-normal-latin.woff2, a 404 on the exact file the browser needs before it can render a single character. Vite does walk the output and prefix matching public assets, but only if you believe it. So I grep the built CSS instead:</p>
<pre><code class="language-css">src: url(&#39;/portfolio/fonts/inter-normal-latin.woff2&#39;) format(&#39;woff2&#39;);</code></pre>
<p>The rewrite happens. It is still worth checking once, because the cost of being wrong is invisible in development and total in production, and there is no error anywhere telling you that your fonts are being requested from the wrong origin.</p>
<h3>Metadata refuses to be relative</h3>
<p>The same intuition, applied to the wrong place, breaks sharing. Open Graph image URLs must be absolute, not because crawlers are incapable of resolving a relative reference, but because they may resolve it against a URL you never intended. Canonical links are the same: a canonical is a statement about where content permanently lives, and a partial path is not a location.</p>
<pre><code class="language-html">&lt;meta property=&quot;og:image&quot;
      content=&quot;https://kashcmdd.github.io/portfolio/og-image.jpg&quot; /&gt;</code></pre>
<h3>A static host has no rewrite rules</h3>
<p>This is the part that decides your routing library. A client-side router wants to own URLs like /journal/your-ladder-needs-to-forget, which requires the server to serve the app shell for any unknown path. GitHub Pages has no such rule. Refresh a deep link and you get a real 404 from a page that genuinely exists.</p>
<p>There is a well-known workaround: drop a 404.html at the site root that reads the path and redirects into the app. It works, and it costs a client-side redirect, a flash of a blank page, and a response whose status code says the page is missing when it is not. For a portfolio, I would rather have the correct status code and no flicker.</p>
<p>Hash routing sidesteps all of it. /#/journal/slug is a fragment, so the server only ever sees the shell, refresh always works, and the back button behaves. It also costs nothing to adopt here: navigation in this app was already driven by scrollIntoView, not by href anchors, so nothing else was using the hash and no sections had to be renamed.</p>
<pre><code class="language-ts">const match = location.hash.match(/^#journal\/([a-z0-9-]+)$/);
if (match) openEntry(match[1]);</code></pre>
<h3>Crawlers still do not run it</h3>
<p>Hash routing fixes refresh for humans and fixes nothing for scrapers. The Facebook and Twitter link previewers do not execute JavaScript, so every hash URL they ever fetch returns the same index.html with the same site-level title. Your article has no identity in a link preview.</p>
<p>The fix is to stop asking the SPA to be the shareable thing. A step after vite build writes a real HTML file for every article, containing that article&#39;s title, description, image and rendered body, served at its own path. The path URL is what gets canonicalised and copied; the hash URL is what the app uses to open the modal on top of a section you were already reading.</p>
<ol><li>Build, then grep the output rather than trusting the config.</li><li>Request every asset from the preview server and confirm the status code, not just that the file exists in dist.</li><li>Confirm each generated article page returns 200 with its own meta tags.</li><li>Treat an absolute URL in metadata as required, and a relative one as a bug.</li></ol>
<p>None of this is difficult. The failure mode is that everything works in dev because dev serves from the root, and then you discover the problem when someone sends you a link that shows nothing. Subpath hosting moves the question from where does this run to where does this get built, and every production 404 I have had on this site has been a URL that nobody rewrote.</p>]]></content:encoded>
    </item>
    <item>
      <title>Markdown Was Never Going to Work Here</title>
      <link>https://kashcmdd.github.io/portfolio/journal/content-model/</link>
      <guid isPermaLink="true">https://kashcmdd.github.io/portfolio/journal/content-model/</guid>
      <description>A type union with six members replaced a format I would have needed three dependencies to render.</description>
      <pubDate>Fri, 25 Sep 2026 00:00:00 GMT</pubDate>
      <category>ARCHITECTURE</category>
      <content:encoded><![CDATA[<p>The journal began as content: string[], with three placeholder entries that were one paragraph of text each. That was enough for placeholders. The first real article needed a code block with a language label and a caption underneath it, and a string cannot carry either.</p>
<p>There were two directions: adopt a markup format and render it, or model the content. I spent a genuinely long time on the first one, because it is the default answer, and the default answer is usually right.</p>
<h3>The case I did not take</h3>
<p>Markdown gives you a standard, a syntax everyone already knows, an ecosystem of renderers, and the ability to paste prose in from anywhere. To render it with code blocks and list styling it wants react-markdown plus remark-gfm plus a syntax highlighter. That is three dependencies on a project where I had just finished removing six unused ones and measured the bundle for it. There is a real cost to that trade being invisible.</p>
<p>Beyond the weight, a format is a negotiation. Theme files decide your margins, a rehype plugin decides whether raw HTML passes through, and the moment you want a block to look a specific way you are configuring a system rather than editing a component. The article stops owning its layout.</p>
<h3>What the union bought</h3>
<pre><code class="language-ts">export type JournalBlock =
  | { type: &#39;paragraph&#39;; text: string }
  | { type: &#39;heading&#39;; text: string }
  | { type: &#39;code&#39;; language: string; code: string; caption?: string }
  | { type: &#39;list&#39;; ordered?: boolean; items: string[] }
  | { type: &#39;quote&#39;; text: string; attribution?: string }
  | { type: &#39;image&#39;; src: string; alt: string; caption?: string };</code></pre>
<ul><li>Invalid content does not compile. A block called &#39;paragraphs&#39;, or a code block with no language, fails tsc before it reaches anyone.</li><li>The renderer is one switch. Five shapes, five cases, no plugin ordering and no AST to learn.</li><li>Structure is data, so it can be rendered by a React modal and by a build step that writes static HTML, from the same array.</li><li>Layout lives next to markup: margins, borders and captions are in the component, not in a theme file two packages away.</li></ul>
<h3>What it actually costs</h3>
<p>Authoring is verbose. Every paragraph is an object, every heading is an object, and an article with forty blocks is four hundred lines of data where Markdown would have been fifty lines of prose. I accepted that because I write five of these a month. If the posts became daily and multiple people wrote them, this model would start to lose.</p>
<p>The more honest limitation: there is no inline formatting. You cannot bold a word inside a paragraph or drop a link mid-sentence without adding an inline block to the union. I left that out on purpose, because six block types cover everything published so far, and a format with an open vocabulary is exactly what starts by serving you and ends up owning you. When a post genuinely needs emphasis, the right move is to add the inline variant, not to import a full markup parser for one `&lt;strong&gt;`.</p>
<h3>Two renderers, and that is the tax</h3>
<p>The modal returns JSX; the generator that writes the static article pages returns HTML strings. So the switch exists twice, in two files, over the same union. The type system will stop an invalid block from being constructed in either one, and it will not stop you from adding a seventh block type in one renderer and forgetting the other. That discipline problem is the price of not using a markup language, and it is a smaller price than the dependency I avoided.</p>
<pre><code class="language-tsx">case &#39;code&#39;:
  return (
    &lt;figure key={key}&gt;
      &lt;div className=&quot;rounded-2xl border border-white/10 bg-black/50&quot;&gt;
        &lt;span className=&quot;text-[10px] font-mono uppercase&quot;&gt;
          {block.language}
        &lt;/span&gt;
        &lt;pre className=&quot;p-4 overflow-x-auto&quot;&gt;
          &lt;code&gt;{block.code}&lt;/code&gt;
        &lt;/pre&gt;
      &lt;/div&gt;
      {block.caption &amp;&amp; &lt;figcaption&gt;{block.caption}&lt;/figcaption&gt;}
    &lt;/figure&gt;
  );</code></pre>
<blockquote><p>Pick a format when the vocabulary is open and the authors are many. Pick a type when the vocabulary is closed and you are the only one writing.</p></blockquote>
<h3>The rule I ended up with</h3>
<p>Six block types, one author, a fixed set of things I want a technical article to contain. That is a closed vocabulary, and a closed vocabulary is what a sum type is for. The content model is forty lines of TypeScript and zero dependencies, and the article you are reading was rendered by a switch statement.</p>]]></content:encoded>
    </item>
    <item>
      <title>A Seasonal Theme Without a Rewrite</title>
      <link>https://kashcmdd.github.io/portfolio/journal/seasonal-theme/</link>
      <guid isPermaLink="true">https://kashcmdd.github.io/portfolio/journal/seasonal-theme/</guid>
      <description>Turning the whole site orange for October with two colours and one CSS filter, and reverting it in a single commit on the first of November.</description>
      <pubDate>Sun, 04 Oct 2026 00:00:00 GMT</pubDate>
      <category>FRONTEND</category>
      <content:encoded><![CDATA[<p>Every seasonal redesign starts with the same temptation: build a theme system. Tokens, a provider, a second palette, a toggle. It is the correct answer for a product that ships themes to customers, and the wrong answer for a personal site that wants to be orange for four weeks a year.</p>
<h3>Two colours, not a design system</h3>
<p>The accent on this site is one short ramp: a light blue that fades into a darker one. It is written literally in the Tailwind classes, the gradients, the focus ring, the code-highlight theme and the static page generator, about a hundred and forty times in total. Swapping those two hex values recolours the buttons, links, rings, glows and gradients everywhere at once, because every one of them already pointed at the same pair.</p>
<pre><code class="language-css">.accent-gradient {
  background: linear-gradient(90deg, #89AACC 0%, #4E85BF 100%);
}</code></pre>
<h3>Recolour the footage, do not film new footage</h3>
<p>The hero plays ambient landscape clips and the footer plays a streamed one. Commissioning matching seasonal footage, licensing it and re-encoding it is a week of work for a background nobody looks at directly. One CSS filter does the same job: it pushes the existing clips toward ember, which is enough to change the mood without touching a single video file.</p>
<pre><code class="language-css">.halloween-video {
  filter: sepia(0.5) hue-rotate(-15deg) saturate(1.4) brightness(0.8) contrast(1.1);
}</code></pre>
<ul><li>Changed: the accent ramp, the loading screen words, a filter on the background videos, a pumpkin favicon and this entry.</li><li>Unchanged: the layout, the components, the data model, the build, and every piece of copy that is not seasonal.</li></ul>
<h3>The revert is the whole point</h3>
<p>Because the work lives on one branch and touches only colours, copy, one class and one asset, undoing it is a revert, not an archaeology project. A seasonal theme that takes a week to remove is worse than no seasonal theme at all, and the calendar is the only thing that decides when this goes away.</p>
<blockquote><p>If you cannot undo a theme in one commit, you did not build a theme. You built a second site.</p></blockquote>]]></content:encoded>
    </item>
  </channel>
</rss>
