logbook

The Equations of Diffusion, Written Out in Full

Thu, 05 Nov 2026 00:00:00 GMT

Diffusion models look intimidating for an unusual reason: the ideas are not that hard, but the equations are long. A single line can contain a product over a thousand timesteps, an expectation over a Gaussian, and a gradient of a log-density, all at once.

These are my notes on what those lines actually mean. I have tried to write every important equation out in full, rather than hiding the details behind "after some algebra".

Throughout, let $x_0 \in \mathbb{R}^d$ be a data point, $x_1, \ldots, x_T$ be a sequence of increasingly noisy versions of it, and $\theta$ be the parameters of a neural network.

The forward process

The forward process is a fixed Markov chain that adds a little Gaussian noise at each step:

$$ q\left(x_t \mid x_{t-1}\right) = \mathcal{N}!\left(x_t;\ \sqrt{1-\beta_t},x_{t-1},\ \beta_t I_d\right) = \frac{1}{\left(2\pi\beta_t\right)^{d/2}} \exp!\left( -\frac{1}{2\beta_t} \left\lVert x_t-\sqrt{1-\beta_t},x_{t-1}\right\rVert_2^2 \right), $$

where $0 < \beta_1 < \cdots < \beta_T < 1$ is a variance schedule chosen by hand. Each step keeps the signal slightly smaller and the noise slightly larger, so the chain drifts from data towards a standard normal distribution.

Because every step is Gaussian and linear, the composition of all the steps is also Gaussian. Define

$$ \alpha_t = 1-\beta_t, \qquad \bar\alpha_t = \prod_{s=1}^{t}\alpha_s . $$

Then the distribution of $x_t$ given the original data has a closed form:

$$ q\left(x_t \mid x_0\right) = \mathcal{N}!\left(x_t;\ \sqrt{\bar\alpha_t},x_0,\ \left(1-\bar\alpha_t\right)I_d\right) = \frac{1}{\left(2\pi\left(1-\bar\alpha_t\right)\right)^{d/2}} \exp!\left( -\frac{\left\lVert x_t-\sqrt{\bar\alpha_t},x_0\right\rVert_2^2} {2\left(1-\bar\alpha_t\right)} \right). $$

Equivalently, and this is the form used in code, we can sample $x_t$ directly by reparameterisation:

$$ x_t = \sqrt{\bar\alpha_t},x_0

\sqrt{1-\bar\alpha_t},\varepsilon, \qquad \varepsilon \sim \mathcal{N}\left(0, I_d\right). $$

The product $\bar\alpha_t$ is the only thing we need to remember about the schedule. When $\bar\alpha_T$ is close to zero, $x_T$ is almost pure noise and carries almost no information about $x_0$.

The reverse direction is the hard part

Generation means running the chain backwards. If we knew the true reverse distribution, we could sample $x_T \sim \mathcal{N}(0,I_d)$ and denoise step by step. Bayes' rule gives an expression for it:

$$ q\left(x_{t-1}\mid x_t\right) = \frac{q\left(x_t\mid x_{t-1}\right),q\left(x_{t-1}\right)}{q\left(x_t\right)} = \frac{ q\left(x_t\mid x_{t-1}\right) \displaystyle\int q\left(x_{t-1}\mid x_0\right)q\left(x_0\right)\mathrm{d}x_0 }{ \displaystyle\int q\left(x_t\mid x_0\right)q\left(x_0\right)\mathrm{d}x_0 }. $$

That is a perfectly correct formula and a completely useless one, because both integrals run over the unknown data distribution. We cannot evaluate it, let alone sample from it.

So we approximate it. Every conditional in the reverse chain is chosen to be Gaussian,

$$ p_\theta\left(x_{t-1}\mid x_t\right) = \mathcal{N}!\left(x_{t-1};\ \mu_\theta\left(x_t,t\right),\ \Sigma_\theta\left(x_t,t\right)\right), $$

and a neural network learns the mean and variance. The question is what objective to train it with.

The evidence lower bound

We would like to maximise the log-likelihood of the data, $\log p_\theta(x_0)$. That is also intractable, so we maximise a lower bound instead. The bound comes from introducing the forward chain as a variational distribution and applying Jensen's inequality:

$$ \log p_\theta\left(x_0\right) = \log \mathbb{E}{q\left(x{1:T}\mid x_0\right)} \left[ \frac{p_\theta\left(x_{0:T}\right)}{q\left(x_{1:T}\mid x_0\right)} \right] \ge \mathbb{E}{q\left(x{1:T}\mid x_0\right)} \left[ \log \frac{p_\theta\left(x_{0:T}\right)}{q\left(x_{1:T}\mid x_0\right)} \right]. $$

Writing the joint distributions out and grouping terms by timestep gives the full expansion:

$$ \begin{aligned} \mathcal{L}{\mathrm{ELBO}}\left(\theta\right) &= \mathbb{E}{q\left(x_{1:T}\mid x_0\right)} \left[ \log p_\theta\left(x_{0:T}\right) -\log q\left(x_{1:T}\mid x_0\right) \right] \ &= \mathbb{E}{q}\left[ \log p\left(x_T\right) +\sum{t=1}^{T}\log p_\theta\left(x_{t-1}\mid x_t\right) -\sum_{t=1}^{T}\log q\left(x_t\mid x_{t-1}\right) \right] \ &= \underbrace{ \mathbb{E}{q}\left[\log p\left(x_T\right)-\log q\left(x_T\mid x_0\right)\right] }{\text{prior term}} -\sum_{t=2}^{T} \underbrace{ \mathbb{E}{q}\left[ \log \frac{q\left(x{t-1}\mid x_t,x_0\right)} {p_\theta\left(x_{t-1}\mid x_t\right)} \right] }{\text{denoising term}} +\underbrace{ \mathbb{E}{q}\left[\log p_\theta\left(x_0\mid x_1\right)\right] }_{\text{reconstruction term}} . \end{aligned} $$

The first term has no learnable parameters: it measures how far the final noisy state is from the prior, and it is small by construction if the schedule is good. The third term is a single denoising step at the end. The interesting part is the sum in the middle.

Each term in that sum is a KL divergence between two Gaussians, because the forward posterior $q(x_{t-1}\mid x_t,x_0)$ is also Gaussian. Deriving it from Bayes' rule gives

$$ q\left(x_{t-1}\mid x_t,x_0\right) = \mathcal{N}!\left(x_{t-1};\ \tilde\mu_t\left(x_t,x_0\right),\ \tilde\beta_t I_d\right), $$

with

$$ \tilde\mu_t\left(x_t,x_0\right) = \frac{\sqrt{\bar\alpha_{t-1}},\beta_t}{1-\bar\alpha_t},x_0

\frac{\sqrt{\alpha_t}\left(1-\bar\alpha_{t-1}\right)}{1-\bar\alpha_t},x_t, \qquad \tilde\beta_t = \frac{1-\bar\alpha_{t-1}}{1-\bar\alpha_t},\beta_t . $$

For reference, the KL divergence between two multivariate Gaussians is

$$ D_{\mathrm{KL}}!\left( \mathcal{N}\left(\mu_q,\Sigma_q\right) \ \Vert
\mathcal{N}\left(\mu_p,\Sigma_p\right) \right) = \frac{1}{2}\left[ \log\frac{\det\Sigma_p}{\det\Sigma_q}

\operatorname{tr}!\left(\Sigma_p^{-1}\Sigma_q\right)
\left(\mu_p-\mu_q\right)^{\top} \Sigma_p^{-1} \left(\mu_p-\mu_q\right) \right]. $$

In our case both covariances are multiples of the identity, so the log-determinant and trace terms are constants with respect to $\theta$. Minimising the KL divergence therefore reduces to matching the means:

$$ \min_\theta\ D_{\mathrm{KL}}!\left( q\left(x_{t-1}\mid x_t,x_0\right) \ \Vert
p_\theta\left(x_{t-1}\mid x_t\right) \right) \quad\Longleftrightarrow\quad \min_\theta\ \left\lVert \mu_\theta\left(x_t,t\right) -\tilde\mu_t\left(x_t,x_0\right) \right\rVert_2^2 . $$

That is the whole trick. A scary sum of KL divergences collapses into a handful of mean-squared errors.

Predicting noise instead of means

The mean $\tilde\mu_t$ depends on $x_0$, which we do not have at sampling time. But the reparameterisation lets us trade $x_0$ for the noise $\varepsilon$ that produced $x_t$:

$$ x_0 = \frac{x_t-\sqrt{1-\bar\alpha_t},\varepsilon}{\sqrt{\bar\alpha_t}} . $$

Substituting that into $\tilde\mu_t$ and simplifying gives the mean in terms of $x_t$ and $\varepsilon$:

$$ \mu_\theta\left(x_t,t\right) = \frac{1}{\sqrt{\alpha_t}}\left( x_t

\frac{\beta_t}{\sqrt{1-\bar\alpha_t}}, \varepsilon_\theta\left(x_t,t\right) \right). $$

So instead of training a network to output a mean, we train it to output the noise that was added. After dropping the per-timestep weighting — which empirically works better than the exact ELBO — the objective becomes the now-familiar denoising loss:

$$ \mathcal{L}{\mathrm{simple}}\left(\theta\right) = \mathbb{E}{t\sim\mathcal{U}{1,\ldots,T}}, \mathbb{E}{x_0\sim q\left(x_0\right)}, \mathbb{E}{\varepsilon\sim\mathcal{N}\left(0,I_d\right)} \left[ \left\lVert \varepsilon

\varepsilon_\theta!\left( \sqrt{\bar\alpha_t},x_0 +\sqrt{1-\bar\alpha_t},\varepsilon,
t \right) \right\rVert_2^2 \right]. $$

In code, that is almost embarrassingly short:

for x0 in loader:
    t = torch.randint(1, T + 1, (x0.shape[0],), device=x0.device)
    eps = torch.randn_like(x0)
    abar = alpha_bar[t].view(-1, 1)
    xt = abar.sqrt() * x0 + (1 - abar).sqrt() * eps
    loss = ((eps - model(xt, t)) ** 2).mean()
    loss.backward()
    optimizer.step()
    optimizer.zero_grad()

Everything else in a diffusion paper is, in some sense, an elaboration of this loop.

The score function and the continuous limit

There is a second way to view the same objective, and it generalises more cleanly. The score of a distribution is the gradient of its log-density:

$$ s_t\left(x\right) = \nabla_x \log q_t\left(x\right). $$

The score points in the direction in which the density grows fastest, which is exactly the direction a sample should move to become more likely. For a Gaussian perturbation of data, the score has a closed form in terms of the noise:

$$ \nabla_x\log q_t\left(x\right) = \frac{\sqrt{\bar\alpha_t}, \mathbb{E}\left[x_0\mid x_t=x\right]-x} {1-\bar\alpha_t} = -\frac{\mathbb{E}\left[\varepsilon\mid x_t=x\right]} {\sqrt{1-\bar\alpha_t}} . $$

This identity is often called Tweedie's formula. It says that denoising and score estimation are the same task up to a scale factor. Training a network $s_\theta(x,t)$ to match the score gives the denoising score matching objective:

$$ \mathcal{L}{\mathrm{DSM}}\left(\theta\right) = \mathbb{E}{t}\left[ \lambda\left(t\right) \mathbb{E}{x_0} \mathbb{E}{\varepsilon} \left[ \left\lVert s_\theta!\left( \sqrt{\bar\alpha_t},x_0 +\sqrt{1-\bar\alpha_t},\varepsilon,
t \right) +\frac{\varepsilon}{\sqrt{1-\bar\alpha_t}} \right\rVert_2^2 \right] \right], $$

where $\lambda(t)$ is a positive weighting. With $\lambda(t) = 1-\bar\alpha_t$ this is equivalent to $\mathcal{L}_{\mathrm{simple}}$.

The continuous-time limit is where the notation becomes genuinely heavy. Let the number of steps go to infinity and replace the discrete schedule with a continuous function $\beta(t)$. The forward process becomes a stochastic differential equation,

$$ \mathrm{d}x = -\frac{1}{2}\beta\left(t\right)x,\mathrm{d}t

\sqrt{\beta\left(t\right)},\mathrm{d}w, $$

where $w$ is a standard Wiener process. The density $q_t(x)$ then evolves according to the Fokker–Planck equation:

$$ \frac{\partial}{\partial t}q_t\left(x\right) = \frac{\beta\left(t\right)}{2} \left[ \nabla\cdot\left(x,q_t\left(x\right)\right) +\Delta q_t\left(x\right) \right], $$

with $\Delta$ the Laplacian. Anderson's reverse-time result says that the time-reversed process is again a diffusion, with an extra drift term built from the score:

$$ \mathrm{d}x = \left[ -\frac{1}{2}\beta\left(t\right)x -\beta\left(t\right)\nabla_x\log q_t\left(x\right) \right]\mathrm{d}t

\sqrt{\beta\left(t\right)},\mathrm{d}\bar w, $$

where $\bar w$ is a Wiener process running backwards in time. This is the continuous version of the reverse chain, and it makes the role of the score explicit: it is the only unknown quantity in the drift.

There is also a deterministic counterpart. Removing the noise from the reverse SDE leaves the probability flow ODE,

$$ \frac{\mathrm{d}x}{\mathrm{d}t} = -\frac{1}{2}\beta\left(t\right) \left[ x +\nabla_x\log q_t\left(x\right) \right], $$

which transports the same marginal densities $q_t(x)$ without any stochasticity. Sampling with a numerical ODE solver is often faster and more reproducible than simulating the SDE, at the cost of some sample diversity.

Guidance

Most practical systems do not sample from the unconditional model. They condition on a prompt $c$ and then exaggerate the conditioning. Classifier-free guidance does this by combining a conditional and an unconditional prediction:

$$ \tilde{\varepsilon}\theta\left(x_t,t,c\right) = \left(1+w\right)\varepsilon\theta\left(x_t,t,c\right)

w,\varepsilon_\theta\left(x_t,t,\varnothing\right), \qquad w \ge 0, $$

where $\varnothing$ denotes the empty condition and $w$ is the guidance scale. In score form the same operation reads

$$ \tilde{\nabla}_x\log q_t\left(x\mid c\right) = \left(1+w\right)\nabla_x\log q_t\left(x\mid c\right)

w,\nabla_x\log q_t\left(x\right), $$

which makes the geometry clearer: guidance adds a multiple of the difference between the conditional and unconditional score fields. Large $w$ pushes samples towards regions the condition considers likely, while shrinking diversity and eventually producing oversaturated artifacts.

Sampling

The reverse chain can be sampled with the ancestral rule implied by $p_\theta$, but many implementations use DDIM, which allows larger strides and a deterministic path. One DDIM update is

$$ x_{t-1} = \sqrt{\bar\alpha_{t-1}}, \underbrace{ \frac{x_t-\sqrt{1-\bar\alpha_t}, \varepsilon_\theta\left(x_t,t\right)} {\sqrt{\bar\alpha_t}} }_{\hat{x}_0}

\sqrt{1-\bar\alpha_{t-1}-\sigma_t^2}, \varepsilon_\theta\left(x_t,t\right)
\sigma_t,\varepsilon, $$

where $\varepsilon\sim\mathcal{N}(0,I_d)$ and $\sigma_t$ controls how much randomness is injected. Setting $\sigma_t=0$ gives the deterministic DDIM sampler; setting $\sigma_t$ to the forward posterior standard deviation recovers the ancestral sampler.

What the equations are really saying

Read quickly, the formulas above look like a pile of Gaussian integrals. Read slowly, they say something simple.

The forward process is a fixed, known corruption. The reverse process is a learned repair. The ELBO turns the impossible problem of matching a whole distribution into a sequence of easy mean-matching problems. Reparameterisation turns those mean-matching problems into noise prediction. Tweedie's formula turns noise prediction into score estimation. The continuous limit replaces the discrete chain with an SDE, and the score becomes the drift. Guidance is just arithmetic on two score fields.

Every long line in a diffusion paper is one of those steps, written without shortcuts. Once the steps are visible, the length stops being intimidating and starts being useful.

view this entry on logbook

Understanding Large Language Models

Wed, 04 Nov 2026 00:00:00 GMT

Large language models can feel almost mysterious from the outside. You give them a prompt, and they produce a response that can explain, summarize, translate, or write code.

But underneath that experience is a fairly understandable set of ideas: tokens, numerical representations, neural networks, and a training process that gradually shapes a model's behaviour.

A simplified view

A language model receives a sequence of tokens and estimates what token is likely to come next. Repeating this process allows it to generate longer sequences.

graph TD
    A[Text prompt] --> B[Tokenizer]
    B --> C[Token IDs]
    C --> D[Transformer model]
    D --> E[Next-token probabilities]
    E --> F[Generated response]

The central idea

At a high level, an autoregressive language model estimates:

$$ P(x_1, x_2, \ldots, x_n) = \prod_{i=1}^{n} P(x_i \mid x_1, \ldots, x_{i-1}) $$

This is only the beginning of the story. The interesting part is how the model learns useful representations and uses attention to relate different parts of a sequence.

A small code example

def greet(name: str) -> str:
    return f"Hello, {name}!"

print(greet("world"))

There is a lot more to unpack, and that's exactly what this publication is for: understanding complicated ideas one layer at a time.

view this entry on logbook

Building a Personal Site with Astro

Wed, 28 Oct 2026 00:00:00 GMT

Every few years I rebuild this site. The stack changes, the design changes, but the goal stays the same: a place to publish that I control, that loads quickly, and that will still make sense in a decade.

This time I settled on Astro. It is a static site generator, which means the output is just HTML, CSS, and a little JavaScript. No database, no server rendering, no framework runtime shipping to the browser unless I explicitly ask for it.

Why static first

A personal site is mostly text. Text does not need a request-time server. It needs a build step, a CDN, and a domain.

Static output gives you a few properties that are hard to retrofit:

Speed. Pages are pre-rendered files. There is nothing to compute on request.
Durability. The build output can be hosted anywhere, including a bucket, GitHub Pages, or a Raspberry Pi in a cupboard.
Debuggability. When something breaks, you can open the generated HTML and see exactly what the browser received.

The trade-off is that anything dynamic has to be handled at build time or in the client. For a publication, that is almost always fine.

Content as files

The articles here are Markdown files with frontmatter. A post looks like this:

---
title: "A title"
description: "A short summary."
date: 2026-10-28
tags: [Web, Notes]
category: Technology
draft: false
---

The content collection schema validates that frontmatter at build time. If I forget a description or write an invalid date, the build fails instead of publishing something broken. That small guardrail is worth more than it sounds.

Because everything is a file, the entire archive is versioned in Git. I can diff a post, revert a typo, or move the whole thing to another machine with a clone.

The build pipeline

At a high level, the pipeline is simple:

graph LR
    A[Markdown files] --> B[Content collection]
    B --> C[Astro build]
    C --> D[Static HTML]
    D --> E[CDN]

Feeds are generated from the same source. RSS, Atom, and JSON Feed are separate endpoints that read the collection, render each entry, and emit XML or JSON. There is no second copy of the content to keep in sync.

What I would change next

view this entry on logbook

The Linux Toolbox I Actually Use

Wed, 14 Oct 2026 00:00:00 GMT

There is a certain genre of blog post that lists fifty command-line tools, most of which you install once and never touch again. This is not that. These are the tools I reach for almost daily, in roughly the order I would miss them.

Navigation and files

fd replaces find for most of my searches. It is faster to type, respects .gitignore by default, and its output is predictable.

fd -e md -x wc -l

ripgrep (rg) does the same for file contents. The default behaviour — recursive, ignores hidden and ignored files, prints line numbers — is exactly what I want ninety percent of the time.

rg "TODO" --type ts

bat is cat with syntax highlighting and line numbers. It is a small quality-of-life improvement that adds up when you read a lot of config files.

Processes and ports

htop is the classic, but I have been using btop more. It is prettier, which sounds frivolous until you spend an afternoon watching a build.

For ports, ss -tulpn is the modern replacement for netstat. When a dev server refuses to start because something already owns port 3000, this is the fastest way to find the culprit.

ss -tulpn | rg 3000

Git

I use lazygit for staging and browsing history, and plain git for everything else. The combination works because lazygit makes it easy to see what changed without running four separate diff commands.

git absorb is the one unusual tool on this list. It takes staged changes and automatically fixes them into the right commits in your branch, which turns an untidy history into something reviewable with very little effort.

Shell

zoxide is a smarter cd. It remembers directories you visit and lets you jump to them by partial name.

z writings

fzf is the fuzzy finder that ties a lot of this together. Piping history, file names, or branches into it is a habit that is hard to give up once acquired.

The point

None of these tools are essential. find, grep, cat, and cd still work, and they are installed everywhere. The value of the replacements is that they remove small frictions — the kind you stop noticing after a while but that quietly shape how willing you are to poke around a system.

A good toolbox is not the longest one. It is the one you know well enough to use without thinking.

view this entry on logbook

Notes on Attention Mechanisms

Wed, 30 Sep 2026 00:00:00 GMT

Attention is one of those ideas that sounds complicated until you find the right analogy, and then it sounds obvious. These are the notes I wish I had when I started reading about transformers.

The problem with recurrence

Before attention, sequence models processed tokens one at a time. A recurrent network carried a hidden state from step to step, compressing everything it had seen into a fixed-size vector. This worked, but it had two costs: it was hard to parallelise, and long-range dependencies tended to fade.

Attention removes the bottleneck. Instead of forcing every token through a single running state, it lets each position look directly at every other position and decide what is relevant.

Queries, keys, and values

The standard explanation uses a library. Each token asks a question (its query), every token advertises what it contains (its key), and the match between them determines how much of each value gets pulled in.

Formally, scaled dot-product attention is:

$$ \text{Attention}(Q, K, V) = \text{softmax}\left(\frac{QK^\top}{\sqrt{d_k}}\right)V $$

The scaling factor $\sqrt{d_k}$ matters. Without it, dot products grow with dimension, the softmax saturates, and gradients become tiny. Dividing by the square root keeps the logits in a reasonable range.

Multiple heads

A single attention operation produces one weighted average. Multiple heads let the model run several of these in parallel, each with its own learned projections.

graph TD
    A[Input embeddings] --> B[Split into heads]
    B --> C[Head 1: local patterns]
    B --> D[Head 2: syntax]
    B --> E[Head N: long-range links]
    C --> F[Concatenate]
    D --> F
    E --> F
    F --> G[Output projection]

The heads are not assigned roles by hand. The hope is that gradient descent discovers useful specialisations on its own, and in practice it often does.

Why it works

Three properties explain most of attention's success:

Parallelism. All positions are processed at once, which maps well onto modern accelerators.
Short paths. Any two tokens are one operation apart, so information does not have to survive a long chain of updates.
Learned weighting. The model decides relevance from data rather than relying on a fixed window.

What it does not solve

Attention is not free. Its cost grows quadratically with sequence length, which is why long-context models invest heavily in efficient variants. It also does not give the model memory in any persistent sense; context is still bounded by what fits in the window.

Understanding the mechanism is useful, but it is only one layer. The rest of the transformer — normalisation, residual streams, feed-forward blocks, and the training objective — matters just as much.

view this entry on logbook

Why I Write in Markdown

Sat, 12 Sep 2026 00:00:00 GMT

I have migrated my notes through at least six applications. Each migration lost something: formatting, attachments, links, or the notes themselves. The only files that survived intact were the ones written in plain text.

Format is a commitment

Every editor wants to be your permanent home. It stores your writing in a structured format, adds features you start to depend on, and quietly makes leaving expensive. This is not malicious. It is just how products work.

Markdown is the opposite of that. It is a set of conventions for annotating plain text, and the underlying file is still readable without any tool at all. If every Markdown application disappeared tomorrow, cat would still show me my writing.

Portability in practice

This site is built from Markdown files. The same files open correctly in Obsidian, VS Code, GitHub, and a terminal pager. When I want to publish, a build step converts them to HTML. When I want to move, I copy a folder.

The important property is not that Markdown is perfect. It is that the failure mode is graceful. A broken link or an unsupported table is a small inconvenience, not a locked door.

What plain text gives up

It gives up some things, honestly:

Rich layout. Complex documents need more than headings and lists.
Embedded media. Images live beside the text rather than inside it.
Structured data. Tables are a compromise, and nested data is awkward.

For prose, none of that matters much. For a spreadsheet or a slide deck, Markdown is the wrong tool, and forcing it is its own kind of lock-in.

A small set of conventions

I keep the syntax narrow on purpose:

# One title per file
## Sections for navigation
**Bold** for emphasis, *italics* sparingly
`code` for identifiers
- lists for enumerations

Frontmatter holds metadata that the prose should not carry: title, date, tags, draft status. Everything else stays in the body.

Writing as a durable act

The real reason I care is that writing is slow. A post might take hours or weeks. Putting that effort into a format controlled by a single company feels like building on rented land. Plain text is boring, and that is exactly the appeal: boring formats do not get discontinued.

view this entry on logbook

A Weekend with a Raspberry Pi

Sat, 22 Aug 2026 00:00:00 GMT

A Raspberry Pi is one of the cheapest ways to make a vague idea concrete. This weekend's idea was a small always-on service: a private dashboard for a few home devices, reachable only from my own network.

The plan

The requirements were deliberately modest:

Run on a Pi 4 with 4 GB of RAM.
Serve a small web app over the local network.
Survive a power cut without manual intervention.
Be quiet, cool, and easy to move.

That last point matters more than it sounds. A server you can pick up and put in a drawer is a server you will actually keep.

Setup

I used a minimal 64-bit image and did the initial configuration over SSH, without ever plugging in a monitor.

ssh pi@raspberrypi.local
sudo apt update && sudo apt full-upgrade -y
sudo timedatectl set-timezone Asia/Kolkata

Setting the timezone early avoids confusing timestamps in logs later, which is the kind of thing you only notice when you are already debugging something else.

Running the service

The app itself runs in a container. Containers are not free — they add a layer and a little overhead — but they make the dependency story clean. If I break something, I delete the container and start again.

services:
  dashboard:
    image: ghcr.io/example/dashboard:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data

restart: unless-stopped is doing a lot of work here. After a power cut, the container comes back without me touching anything.

What went wrong

Two things, predictably.

First, the Pi throttled under load because it was sitting in a closed case with no airflow. Moving it onto a small stand dropped the temperature by about fifteen degrees, which was enough to stop the throttling.

Second, raspberrypi.local stopped resolving after a router reboot. mDNS is convenient until it is not. I added a static DHCP lease and started using the IP address for anything that needed to be reliable.

Was it worth it

Yes, but not for the reasons I expected. The service is useful, but the real value was the reminder that small systems are understandable. There is no orchestration layer, no cloud console, no hidden abstraction. When something breaks, I can trace it from the process to the container to the kernel without leaving the machine.

That is a nice property for a weekend project, and an even nicer one for a tool you plan to keep.

view this entry on logbook

Reading Code You Didn't Write

Sat, 18 Jul 2026 00:00:00 GMT

Most of the code I work with was written by someone else. Sometimes that someone is a stranger, sometimes a teammate, and sometimes a past version of me with different priorities and a worse memory. Getting oriented quickly is a skill, and like most skills it improves with a routine.

Start at the edges

Do not begin at main. Begin where the program meets the outside world: routes, CLI commands, event handlers, or exported functions. These are the entry points, and they tell you what the system is for before you drown in how it works.

A useful first pass is to list the entry points and write one sentence for each:

What triggers it?
What does it return or change?
What does it depend on?

That list is often enough to sketch the architecture.

Follow one path end to end

Pick the most common operation and trace it from entry point to storage and back. Read every function on the way, but do not try to understand every branch. The goal is a spine you can hang later details on.

graph LR
    A[HTTP request] --> B[Router]
    B --> C[Handler]
    C --> D[Service]
    D --> E[Database]
    E --> D
    D --> C
    C --> F[Response]

Once you have one working path, the rest of the codebase becomes variations on a theme.

Read the tests as documentation

Tests are the only part of a codebase that states intended behaviour explicitly. They also tell you what the authors were afraid of breaking. A test suite is usually a better introduction than a README, because it cannot silently drift out of date without failing.

Start with the tests for the path you just traced. They will confirm your understanding and reveal edge cases you would have missed.

Use the tools, but sparingly

Search and navigation tools are essential, but they can also keep you at the surface. Jumping from definition to definition feels productive while building very little understanding.

A better rhythm is to read a full file, then search for one specific term. Alternate between depth and breadth instead of doing either exclusively.

Keep a map

I keep a scratch file while exploring. It contains the entry points, the main data structures, and a list of questions. The questions are the most valuable part, because they turn confusion into something I can resolve deliberately.

By the end of a day, the map is usually messy and half wrong. That is fine. The act of writing it is what turns a pile of files into a system you can reason about.

view this entry on logbook