DEV Community: Satyam Shree

[Boost]

Satyam Shree — Tue, 13 Oct 2026 21:09:48 +0000

Satyam Shree

Oct 6

I Built My Own Local-First AI Assistant in Go — Meet Nox

#ai #programming #agents #agentaichallenge

7 min read

I Built My Own Local-First AI Assistant in Go — Meet Nox

Satyam Shree — Tue, 06 Oct 2026 10:56:04 +0000

Alexa and Google Assistant are incredibly convenient.

But there was one thing that kept bothering me:

Why does my personal assistant need somebody else's cloud to think?

I wanted something different.

An assistant running on hardware I control.

Speech recognition running locally.

The LLM running locally.

My automations staying local.

And most importantly, an AI model that doesn't automatically get permission to do whatever it wants on my machine.

So I started building Nox.

GitHub: https://github.com/satya-sudo/NoxAgent

What is Nox?

Nox is a local-first personal voice assistant written primarily in Go.

The goal is eventually to have something similar to an Alexa/Google Home-style assistant, except the intelligence and orchestration live on hardware I control.

Right now I can say things like:

Hey Nox

Play Numb on YouTube Music

Set a timer for 10 minutes

Turn on the living room lights

Check my email

Search Google for weather in Delhi

Make the T-Beamer warm and 20%

Tell me something about the Moon

And Nox decides whether the request should be handled by deterministic code or by the local LLM.

It currently supports:

Local speech recognition
Local LLM conversations
Contextual follow-up questions
Google Search
YouTube Music control
Persistent timers and alarms
Home Assistant
Read-only Gmail access
Direct WiZ device control over LAN
A web dashboard
A terminal client
An HTTP API

And it can run without a cloud speech or conversational AI API.

The Architecture

The architecture currently looks roughly like this:

Browser microphone / terminal / HTTP client
                    |
                    v
             Go API + Dashboard
                    |
        +-----------+-----------+
        |           |           |
        v           v           v
   whisper.cpp   Intent      Qwen +
     Local STT    Rules     llama.cpp
        |           |           |
        +-----------+-----------+
                    |
          Validated Action Layer
                    |
       +------------+-------------+
       |            |             |
       v            v             v
 Browser Bridge   Scheduler   Home Assistant
 Google/YT Music  Timers      Local devices
                  Alarms

There is a fairly important design decision hidden inside that diagram.

The LLM is not the operating system.

It's a reasoning component.

That distinction became increasingly important while I was building Nox.

Why Go?

I wanted the assistant itself to behave more like infrastructure than an AI demo.

It needs to:

run continuously,
expose APIs,
coordinate concurrent operations,
manage timers,
persist state,
communicate with local services,
control devices,
communicate with browsers,
and eventually run as a long-lived Linux service.

Go fits that model extremely well.

The repository is split into components such as:

cmd/noxd/                 daemon
cmd/noxctl/               CLI client

internal/api/             HTTP API + dashboard
internal/assistant/       orchestration
internal/intent/          deterministic intent parser
internal/llm/             local LLM client
internal/voice/           whisper.cpp integration
internal/browser/         browser action broker
internal/scheduler/       timers and alarms
internal/homeassistant/   Home Assistant client
internal/gmail/           Gmail integration
internal/wiz/             WiZ LAN control
internal/notify/          notifications

Instead of placing everything inside one giant AI-agent loop, each capability has a clearly defined responsibility.

That makes adding new integrations much less chaotic.

The LLM Shouldn't Handle Everything

One realization I had fairly early was:

Not every command needs AI.

Consider:

set a timer for 10 minutes

There is little reason to spend several seconds asking an LLM what that means every time.

Nox therefore has deterministic intent handling for common operations.

For known commands:

User
  ↓
Intent Parser
  ↓
Registered Action
  ↓
Execute

For requests that don't match those deterministic paths:

User
  ↓
Local LLM
  ↓
Structured Action
  ↓
Validation
  ↓
Execute

And normal conversational questions can simply go to the model.

This gives me a useful combination:

Rules for predictable operations.

LLMs for ambiguity.

Giving an LLM Access to Your Computer Is Slightly Terrifying

Once Nox could understand language, the obvious next step was allowing it to perform actions.

That's also where things become dangerous.

A naive implementation might effectively do:

LLM generates command
       ↓
execute(command)

I absolutely did not want that.

Nox instead validates model-selected actions against a fixed allowlist.

The model can select registered operations.

It cannot decide:

Actually, run this shell command.

Or:

Execute this random JavaScript.

Or:

Access this completely unrelated service.

For example, browser interactions are represented as typed operations such as:

youtube_music.pause
youtube_music.next
youtube_music.set_volume
browser.google_search

rather than arbitrary JavaScript.

The model can choose from capabilities that I explicitly exposed.

That pattern is something I increasingly believe local agents should follow:

LLM
 ↓
Intent
 ↓
Capability boundary
 ↓
Validation
 ↓
Execution

Not:

LLM
 ↓
God mode

Local Speech Recognition with Whisper

For speech-to-text, Nox uses whisper.cpp.

So the voice pipeline is essentially:

Microphone
   ↓
WAV
   ↓
whisper.cpp
   ↓
Text
   ↓
Nox

No cloud speech API is required.

The browser dashboard can work in push-to-talk mode, but I've also been working on making the interaction feel more like an actual home assistant.

For example:

"Hey Nox"

Nox responds:

"Sir."

and opens a short window for the next command.

You can also combine everything:

Hey Nox, play Not Sober

It's a small detail, but it changes the project from feeling like an API with a microphone attached into something closer to an actual assistant.

Running the Brain Locally

For general conversation Nox talks to an OpenAI-compatible local model server.

My current reference setup uses:

Qwen3 4B
+
llama.cpp

For example:

llama-server \
  -hf Qwen/Qwen3-4B-GGUF:Q4_K_M \
  --alias nox-local \
  --host 127.0.0.1 \
  --port 8080 \
  -c 4096 \
  --jinja

Nox then communicates with that local endpoint.

This means questions such as:

Tell me something about the Moon.

can be handled locally.

And because Nox keeps recent conversation context, I can follow with:

How long does it take to orbit us?

without repeating the subject.

Browser Automation Without Giving AI the Browser

Music control presented another interesting challenge.

I wanted commands like:

Play Numb on YouTube Music
pause
next
set volume to 40%
what song is playing?

Nox uses a Chromium extension as a browser bridge.

But again, I didn't want the backend—or especially the LLM—to send arbitrary JavaScript into the browser.

The extension therefore understands specific typed actions.

The browser integration is currently restricted to a small set of origins including localhost, Google Search, and YouTube Music.

It isn't trying to become a generic browser agent.

At least for now, I prefer:

small capabilities with explicit permissions

over

AI can control the entire browser.

Home Automation

This was one of the main reasons I wanted to build Nox in the first place.

Through Home Assistant, Nox can perform commands such as:

Turn on the living room lights.

Turn off the coffee machine switch.

Activate scene movie night.

What's the bedroom temperature?

But I also wanted Nox to work with some devices without requiring another orchestration layer.

So I added native WiZ LAN control directly in Go.

Nox can discover compatible devices over the local network and communicate with them over UDP.

For example:

Turn on the T-Beamer.

Make the T-Beamer warm and 20%.

No LLM API.

No cloud automation service.

No MCP subprocess.

Just:

Voice
 ↓
Nox
 ↓
LAN
 ↓
Device

I really like this part of the architecture.

The closer an operation can stay to my local network, the better.

Email — But Intentionally Read Only

Nox also integrates with Gmail.

But this is another place where I've deliberately limited what the assistant can do.

Right now it can:

Check my email.

Search Gmail for from:alice

It can retrieve things like:

sender
subject
date
snippet
message ID

But the Gmail integration is read-only.

Nox cannot:

send email,
delete email,
archive messages,
modify messages.

Could I add those features?

Of course.

But once an AI assistant can affect external systems, permissions deserve much more thought than:

The API supports it, so let's expose it.

Read access and write access are very different trust boundaries.

Timers That Survive Restarts

Timers seem trivial until you want an assistant running continuously.

Suppose I say:

Set a timer for 30 minutes.

and restart Nox ten minutes later.

I don't want that timer disappearing.

Nox therefore persists timers and alarms locally and recovers scheduled events when it starts again.

This is one of those features that isn't particularly impressive in a demo, but matters enormously when turning a project into something you genuinely use.

Local-First Doesn't Mean "Never Use the Internet"

An important clarification:

Nox is local-first, not magically disconnected from the outside world.

If I ask it to search Google, Google obviously receives a request.

If I play something from YouTube Music, YouTube is involved.

If I ask it to check Gmail, Gmail's API is involved.

The difference is that speech processing and conversational reasoning don't inherently require sending the conversation to an AI provider.

And integrations are explicit rather than being the foundation of the assistant itself.

Running Nox

The current reference environment is macOS, while Linux is the long-term deployment target.

You'll need Go plus the local model runtimes:

brew install whisper-cpp llama.cpp

Download a Whisper model:

mkdir -p models

curl -L \
  https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.en.bin \
  -o models/ggml-base.en.bin

Start the local LLM:

llama-server \
  -hf Qwen/Qwen3-4B-GGUF:Q4_K_M \
  --alias nox-local \
  --host 127.0.0.1 \
  --port 8080 \
  -c 4096 \
  --jinja

Then configure Nox:

export NOX_WHISPER_BIN="$(command -v whisper-cli)"
export NOX_WHISPER_MODEL="$PWD/models/ggml-base.en.bin"
export NOX_WHISPER_LANGUAGE=en

export NOX_LLM_URL=http://127.0.0.1:8080
export NOX_LLM_MODEL=nox-local

make run

By default, Nox listens on:

127.0.0.1:7080

Then open:

http://127.0.0.1:7080/

Or just talk to it from the terminal:

go run ./cmd/noxctl "what time is it"

go run ./cmd/noxctl "set a timer for 10 minutes"

go run ./cmd/noxctl "play Numb on YouTube Music"

What I'm Building Toward

Nox is still in active development.

There are plenty of things I want to improve.

Especially:

native Linux wake-word detection,
fully offline speech output,
better device integrations,
more natural conversational automation,
stronger long-term memory,
improved wake-word handling,
richer local automation,
and running the whole system continuously on dedicated Linux hardware.

The end goal isn't really:

Build another Alexa.

It's closer to:

Build a personal computing layer that I can talk to.

One where I control:

the model,
the data,
the integrations,
the permissions,
the hardware,
and the source code.

One Thing This Project Changed My Mind About

Before building Nox, I thought the LLM would be the difficult and interesting part.

It isn't.

Running a model locally is surprisingly straightforward now.

The really interesting problems are everything around the model:

permissions
state
scheduling
speech
latency
device discovery
browser communication
failure recovery
context
security boundaries

The LLM might be the brain.

But an assistant needs a nervous system.

That's the part I'm enjoying building.

If you want to explore the code, contribute, suggest an integration, or just follow the project:

GitHub: https://github.com/satya-sudo/NoxAgent

I'd also genuinely love feedback from people building local AI systems.

Especially around one question:

How much authority should we actually give local AI agents?

#golang #ai #opensource #homeautomation

I Built Tic-Tac-Toe the Old Way — Before Coding Agents

Satyam Shree — Sat, 26 Sep 2026 14:11:35 +0000

What I did.

I recently built a multiplayer Tic-Tac-Toe backend in Go.

At first, it sounds almost too simple to be worth writing about.

It has a 3×3 board.

Two players.

Some HTTP endpoints.

A WebSocket connection.

Done.

But somewhere along the way, a tiny game turned into a surprisingly good exercise in backend engineering.

And I deliberately built this one the old way.

No coding agent writing the implementation.
No prompt → generate → test → fix loop.

I wanted to sit with the problem, make the design decisions myself, write the code, break it, debug it, and understand why every piece existed.

That was the actual point of the project.

The final result

The frontend ended up looking much nicer than the backend deserves. 😄

The important part for me, though, was everything happening behind that board.

The server handles:

Creating games
Joining games
Starting games
Making moves
Validating moves
Checking winners
Managing turns
Maintaining game state
Managing WebSocket connections
Broadcasting game updates

The API roughly looks like:

POST /games
GET  /games/{gameId}

POST /games/{gameId}/join
POST /games/{gameId}/start
POST /games/{gameId}/moves

GET  /games/{gameId}/ws

The last endpoint was where things got interesting.

Why Tic-Tac-Toe?

Because I didn't want the problem itself to be difficult.

When learning backend architecture, it's easy to pick a complicated project and then spend most of your time fighting the domain.

I wanted something where the rules could fit in my head.

Board
 ↓
Players
 ↓
Turns
 ↓
Moves
 ↓
Winner

That leaves enough mental space to think about the engineering around it.

How should the game be represented?

Who owns the state?

Who validates a move?

How do multiple games exist at the same time?

How does a player connect to a game?

How do both players know when something changed?

Those questions were more interesting to me than Tic-Tac-Toe itself.

Starting with the simplest model

The first thing I needed was a board.

Nothing fancy.

type boardStatus int

const (
    emptyCell boardStatus = iota
    player1
    player2
)

And:

type Board struct {
    board [][]boardStatus
}

Creating the board:

func NewBoard() Board {
    board := make([][]boardStatus, 3)

    for i := range 3 {
        board[i] = make([]boardStatus, 3)
    }

    return Board{
        board: board,
    }
}

The interesting part wasn't creating a 3×3 array.

It was deciding where the responsibility for the board should live.

I didn't want HTTP handlers deciding whether a move was valid.

The game should know its own rules.

So the direction became:

HTTP Handler
     ↓
GameManager
     ↓
Game
     ↓
Board

The handler deals with HTTP.

The manager deals with games.

The game deals with game rules.

That separation made the code much easier to reason about.

The GameManager

Once I had one game, the next obvious problem was:

What happens when there are 100 games?

The answer wasn't to make the handler keep track of them.

I introduced a GameManager.

Conceptually:

GameManager
    │
    ├── Game A
    ├── Game B
    ├── Game C
    └── Game D

The manager became responsible for things like:

CreateGame()
GetGame()

The HTTP layer doesn't need to know how games are stored.

It just asks:

game, err := h.gameManager.GetGame(gameID)

That small separation is something I probably wouldn't have appreciated as much without actually building it.

Then came HTTP

Go's net/http made the API surprisingly simple.

mux := http.NewServeMux()

mux.HandleFunc("POST /games", handler.CreateGame)
mux.HandleFunc("GET /games/{gameId}", handler.GetGame)

mux.HandleFunc("POST /games/{gameId}/join", handler.JoinGame)
mux.HandleFunc("POST /games/{gameId}/start", handler.StartGame)
mux.HandleFunc("POST /games/{gameId}/moves", handler.Move)

mux.HandleFunc("GET /games/{gameId}/ws", handler.WebSocket)

One thing I liked here was being able to use method-aware routes directly:

"POST /games/{gameId}/moves"

instead of having one handler manually inspect:

r.Method

The API started to feel like an actual backend rather than a collection of functions.

Designing the game rules

This is where simple problems are deceptive.

A move isn't just:

board[row][column] = player

You need to answer:

Does the game exist?
Has the game started?
Is the game already finished?
Is this actually the player's turn?
Is the position already occupied?
Is the requested position valid?
Did this move win the game?
Is the board full?

Those rules belong to the domain.

Not inside the HTTP handler.

For example:

func (g *Game) CheckWinner() (string, error) {
    // check rows
    // check columns
    // check diagonals
}

That led to one of the biggest lessons from this project:

A handler shouldn't know how your business works. It should know how to talk to your business logic.

Then I wanted real-time updates

The HTTP API worked.

I could make a move.

But there was an obvious problem.

If Player 1 makes a move:

Player 1
   │
   │ POST /moves
   ▼
Server

how does Player 2 know?

They could repeatedly call:

GET /games/{gameId}

but that's polling.

I wanted the server to say:

Something changed. Here's the new state.

That's where WebSockets came in.

Understanding WebSockets instead of just using them

The WebSocket endpoint became:

GET /games/{gameId}/ws

The important thing I learned is that a WebSocket starts as an HTTP request and then gets upgraded into a persistent connection.

Conceptually:

HTTP Request
     │
     ▼
WebSocket Upgrade
     │
     ▼
Persistent Connection
     │
     ├── Server → Client
     └── Client → Server

Once upgraded, the server can keep the connection alive and send messages whenever something happens.

ConnectionManager

This created another responsibility.

The Game shouldn't know about TCP connections.

The GameManager shouldn't know about WebSocket connections.

So I created a ConnectionManager.

Something conceptually like:

type ConnectionManager struct {
    connections map[string][]*websocket.Conn
}

The key is the gameID.

So:

game-123
   ├── Player 1 connection
   └── Player 2 connection

game-456
   ├── Player 1 connection
   └── Player 2 connection

And then:

func (cm *ConnectionManager) Broadcast(gameID string, message any) {
    // send message to all connections for this game
}

This was one of those design decisions that seems obvious after you arrive at it.

But getting there yourself is the useful part.

The connection manager shouldn't care whether the message means:

game started

or:

player moved

or:

game over

It should just deliver the message.

`any` or a common WebSocket message?

I also had to think about how WebSocket messages should be represented.

One option:

func (cm *ConnectionManager) Broadcast(
    gameID string,
    message any,
)

That keeps the connection manager generic.

Then the caller can send:

cm.Broadcast(gameID, message)

Another option is to define a common envelope:

type WSMessage struct {
    Type string `json:"type"`
    Data any    `json:"data"`
}

So the client receives:

{
    "type": "game_update",
    "data": {
        "currentPlayer": "player2"
    }
}

I liked this approach because the transport layer stays generic while the client still has a predictable event format.

The architecture started to emerge

At this point the project roughly looked like:

                    HTTP
                     │
                     ▼
              ┌─────────────┐
              │ GameHandler │
              └──────┬──────┘
                     │
                     ▼
              ┌─────────────┐
              │ GameManager │
              └──────┬──────┘
                     │
                     ▼
                  ┌─────┐
                  │Game │
                  └─────┘
                     │
                     │ state changed
                     ▼
              ┌──────────────┐
              │ Connection   │
              │ Manager      │
              └──────┬───────┘
                     │
              ┌──────┴──────┐
              ▼             ▼
          Player 1       Player 2
           WebSocket      WebSocket

That's probably the most valuable thing I got from the project.

Not Tic-Tac-Toe.

Not WebSockets.

Learning to assign responsibilities.

Things that broke

Of course, it wasn't this clean while I was writing it.

There were plenty of moments where I had to stop and ask:

Who should actually be responsible for this?

For example:

Should the handler validate the game ID?
Should the GameManager know about WebSockets?
Should the Game know about connections?
Where should winner detection happen?
Who removes a disconnected WebSocket?
What happens when a WebSocket dies?
Should messages be strongly typed?
What exactly should be broadcast?
Should the client receive the entire game state or only the event?

These aren't syntax problems.

They're design problems.

And they're much harder to solve by memorizing Go syntax.

What I learned about Go

This project also gave me a much better feel for some Go fundamentals.

`net/http`

I got more comfortable with:

http.NewServeMux()

and handlers:

func (h *GameHandler) Move(
    w http.ResponseWriter,
    r *http.Request,
)

Structs and composition

Instead of creating giant objects, I could make small components with focused responsibilities.

Errors

I started thinking more carefully about where errors should be created and where they should be translated into HTTP responses.

For example, a domain error doesn't necessarily need to know anything about:

http.StatusBadRequest

The HTTP layer can make that decision.

Maps

Managing games and connections naturally led to maps.

Pointers

WebSocket connections and mutable game state made pointer semantics much more relevant.

Concurrency

This is probably the next area I want to go deeper into.

A real multiplayer server means multiple requests can interact with the same game state.

That immediately raises questions around:

Race conditions
Mutexes
Concurrent map access
Connection lifecycle
Goroutines

And that's where a "toy" game starts becoming a useful systems exercise.

Why I didn't use a coding agent

This is probably the most important part of the project for me.

We are in a time where you can describe:

"Build me a multiplayer Tic-Tac-Toe server in Go with WebSockets"

and get a surprisingly large amount of working code.

That's incredibly useful.

But I wanted to experience something different.

I wanted to sit down with the problem and do:

Problem
   ↓
Think
   ↓
Design
   ↓
Write
   ↓
Compile
   ↓
Break
   ↓
Debug
   ↓
Understand
   ↓
Refactor

instead of:

Prompt
   ↓
Generated code
   ↓
Run
   ↓
Fix generated code

I didn't use an AI coding agent to implement this project.

I wrote it myself.

Not because I think using AI is bad.

Quite the opposite.

AI coding tools are going to be an important part of how software gets built.

But I think there's value in knowing what it feels like to build something before handing the implementation over to an agent.

Because when you eventually use an agent, understanding the underlying system changes the questions you ask it.

You can look at generated code and ask:

Why is this connection manager responsible for that?

instead of:

Does this compile?

That distinction matters.

The uncomfortable part of building without an agent

The old way is slower.

There's no point pretending otherwise.

You spend 20 minutes figuring out something that an agent could probably produce in 20 seconds.

You forget an API.

You make stupid mistakes.

You stare at an error.

You rewrite something you thought was finished.

You search documentation.

You write a bad implementation and then realize why it's bad.

But those mistakes are also where some of the learning happens.

The first time you personally run into a race condition, "concurrency" stops being a topic from a textbook.

The first time your WebSocket connection disappears unexpectedly, connection lifecycle becomes real.

The first time your handler starts becoming 200 lines long, separation of concerns stops being an architectural buzzword.

What I would change next

This is still a small project.

There are plenty of things I'd improve.

Persistence

Currently the game state is in memory.

A server restart means goodbye games.

Eventually:

PostgreSQL / Redis

could be introduced depending on the requirements.

Authentication

Players are currently identified at a very basic level.

A real game would need player identity and authorization.

Reconnection

What happens if someone closes their laptop for 10 seconds and comes back?

The game shouldn't necessarily be over.

Concurrency

The game state needs proper synchronization when multiple requests can modify it concurrently.

WebSocket lifecycle

I'd like to make connection registration/removal and dead connection handling more robust.

Tests

The game rules are a perfect candidate for unit tests.

Things like:

horizontal win
vertical win
diagonal win
draw
invalid move
wrong player's turn
game already finished

should all be tested.

What started as Tic-Tac-Toe

The funny thing is that I didn't really build Tic-Tac-Toe.

I built a tiny environment where I could practice:

API design
Domain modeling
Separation of concerns
State management
WebSockets
Event broadcasting
Error handling
Concurrency
Go
Debugging
Making architectural decisions

And that's probably why I enjoyed it.

The game is simple.

The engineering isn't.

Final thought

There is a temptation right now to measure productivity by how quickly we can get from an idea to working code.

And AI makes that distance incredibly small.

But sometimes I think it's worth deliberately taking the long route.

Build something.

Get stuck.

Read the documentation.

Make the wrong abstraction.

Delete it.

Build it again.

Understand why it works.

Then, when you bring an AI coding agent into the process later, you're not just someone who can generate software.

You're someone who can understand software.

That's a much more interesting skill to have.

Built with: Go · net/http · WebSockets

No AI coding agent was used to implement the project.

If you're interested, the source code is here:

👉 GitHub repository

This is a personal learning project, and the architecture will probably evolve as I continue experimenting with it.

[Boost]

Satyam Shree — Sat, 01 Aug 2026 14:53:41 +0000

Satyam Shree

Jul 29

I Got Tired of Rewriting Segment Trees in Go... So I Published One

#go #algorithms #opensource

2 min read

I Got Tired of Rewriting Segment Trees in Go... So I Published One

Satyam Shree — Wed, 29 Jul 2026 06:29:44 +0000

If you've solved enough competitive programming problems, you've probably written a segment tree more times than you'd like to admit.

Every contest.
Every new repository.
Every interview.

The same build(), query(), update() functions over and over again.

So I decided to stop rewriting it and turn it into a reusable Go package.

Why?

Go has fantastic standard libraries, but when it comes to common data structures used in algorithms, I often find myself copying old code from previous solutions.

I wanted something that I could simply install and use:

go get github.com/satya-sudo/segmenttree

instead of searching through old repositories.

Design Goals

While building the package, I tried to keep a few principles in mind:

Simple API
Generic implementation (works beyond just integer sums)
Fast point updates
Efficient range queries
Easy to plug into competitive programming as well as real projects

The goal wasn't to build the most feature-rich segment tree ever—it was to build one that I'd actually enjoy using.

Typical Operations

A segment tree gives you:

Build in O(n)
Range Query in O(log n)
Point Update in O(log n)

Which makes it incredibly useful for problems involving:

Range Sum
Range Minimum
Range Maximum
GCD queries
XOR queries
Any associative operation

Why publish it?

One thing I've been trying to do this year is stop treating useful code as "just another snippet."

If something solves a recurring problem, it deserves to be packaged, documented, versioned, and shared.

Open source isn't only about building huge frameworks.

Sometimes it's about removing a tiny bit of friction for the next developer—including your future self.

Repository

⭐ GitHub: https://github.com/satya-sudo/segmenttree

I'd love feedback, feature requests, or even criticism.

If you find it useful, consider giving it a star. It motivates me to keep building more Go libraries.

I'm planning to open-source more reusable Go utilities over the coming months instead of letting them live inside personal repositories.

If there's a data structure or utility you wish existed as a clean Go package, let me know.

A Practical Guide to Temporal Versioning in Neo4j: Nodes, Relationships, and Historical Graph Reconstruction

Satyam Shree — Fri, 05 Dec 2025 08:38:36 +0000

Modern graph databases often represent dynamic systems: applications evolving over time, relationships appearing and disappearing, and entities acquiring new attributes as data changes.
When the underlying graph is user-facing, maintaining a complete history of nodes and relationships becomes a critical capability.

This article presents a production-grade, bitemporal versioning model for Neo4j, supporting:

Accurate historical reconstruction
Time-travel queries
Temporal relationship tracking
Efficient ingestion
Minimal impact on existing “current” queries

The approach is designed for high-read systems where graph state changes incrementally and users must view data at any point in time.

1. Design Goals

A temporal graph versioning system must satisfy the following constraints:

1.1 Minimal disruption to existing queries

Everyday queries (fetching the “current” graph) must remain simple:

MATCH (n) WHERE NOT n:Deleted
MATCH ()-[r]->() WHERE r.Status = "Active"

No complex temporal logic in the majority of queries.

1.2 Complete bitemporal representation

Every node or relationship must encode:

StartDate — when it became valid
EndDate   — when it stopped being valid (NULL = current)

This enables time-travel queries and historical reconstruction.

1.3 Deterministic version merging

Each node and relationship must have a stable primary key so the ingestion pipeline can decide:

Should this entity be created?
Should it be updated?
Should old versions be closed?

1.4 Efficient deletion detection

We cannot “blindly” delete nodes. Instead, the pipeline must:

Mark entities touched in this ingestion cycle (via lastUpdated)
Infer deletions by comparing against the process date

1.5 Neo4j MERGE limitations must be respected

Neo4j does not support:

MERGE (a)-[r:LINK {EndDate: NULL}]->(b)

This is why relationships use a Status property rather than attempting NULL-based merges.

2. Data Model

2.1 Versioned Nodes

Each logical entity is represented as multiple immutable node versions:

(:Entity {
    Id: "E123",
    StartDate: datetime("2024-01-10T00:00:00Z"),
    EndDate: null,
    lastUpdated: datetime("2024-12-01T10:00:00Z")
})

When a node becomes invalid:

EndDate is set
:Deleted label is added

ASCII Diagram

+------------------+        +------------------+
| Entity (v1)      | ----> | Entity (v2)      |
| Id: E123         |       | Id: E123         |
| Start: T1        |       | Start: T2        |
| End: T2          |       | End: null        |
| Label: Deleted   |       | Label: <none>    |
+------------------+        +------------------+

2.2 Versioned Relationships

Like nodes, relationships also maintain temporal state:

(a)-[:LINK {
    Id: "R987",
    StartDate: datetime("2024-01-10T00:00:00Z"),
    EndDate: null,
    Status: "Active",
    lastUpdated: datetime("2024-12-01T10:00:00Z")
}]->(b)

Why we need `Status`

Neo4j cannot MERGE on EndDate = NULL, so we use:

Status = "Active"
Status = "Deleted"

This provides a safe, deterministic merge target.

3. Ingestion Architecture (Multi-Phase)

Your ingestion pipeline comprises three phases, ensuring consistent versioning.

+-----------------------------------------------------+
|                Ingestion Pipeline                   |
+-----------------------------------------------------+
|                                                     |
| Phase 1: Nodes      → Create or update nodes        |
| Phase 2: Links      → Create or update relationships|
| Phase 3: Clean-up   → Close missing versions        |
|                                                     |
+-----------------------------------------------------+

3.1 Phase 1 — Node Ingestion

For each incoming node:

MERGE by Id
If node exists and attributes differ → close old version, create new
Update lastUpdated = processTime

Cypher (simplified)

MERGE (n:Entity {Id: $id})
ON MATCH SET
    n.lastUpdated = $processDate
ON CREATE SET
    n.StartDate = $processDate,
    n.lastUpdated = $processDate

When detecting changes, the ingestion process may:

Set EndDate on the previous version
Add :Deleted
Create a fresh version

3.2 Phase 2 — Relationship Ingestion

For each incoming relationship:

MATCH (a:Entity {Id: $src})
MATCH (b:Entity {Id: $dst})

MERGE (a)-[r:LINK {Id: $id}]->(b)
ON MATCH SET
    r.lastUpdated = $processDate
ON CREATE SET
    r.StartDate = $processDate,
    r.Status = "Active",
    r.lastUpdated = $processDate

If a relationship changed (attribute changes), the pipeline must:

Mark old relationship as:
- r.EndDate = $processDate
- r.Status = "Deleted"
Create a new version:
- StartDate = $processDate
- Status = "Active"

3.3 Phase 3 — Version Closure (Deletion Detection)

After phases 1 & 2, you detect deletions:

Any node whose lastUpdated != processDate is no longer valid:

MATCH (n:Entity)
WHERE n.lastUpdated <> $processDate AND NOT n:Deleted
SET n.EndDate = $processDate, n:Deleted

Same for relationships:

MATCH ()-[r:LINK]->()
WHERE r.lastUpdated <> $processDate AND r.Status = "Active"
SET r.EndDate = $processDate, r.Status = "Deleted"

This allows ingestion to determine “missing = deleted” without manual intervention.

4. Querying the Current Graph

Your versioning design enables extremely simple “current state” queries:

Nodes

MATCH (n:Entity)
WHERE NOT n:Deleted
RETURN n

Relationships

MATCH (a)-[r:LINK]->(b)
WHERE r.Status = "Active"
RETURN a, r, b

Minimal logic.
High performance.
Clean integration with UI/API.

5. Querying Historical Snapshots

To reconstruct graph state for a given timestamp T:

Nodes

MATCH (n:Entity)
WHERE n.StartDate <= $T AND (n.EndDate IS NULL OR n.EndDate > $T)
RETURN n

Relationships

MATCH (a)-[r:LINK]->(b)
WHERE r.StartDate <= $T AND (r.EndDate IS NULL OR r.EndDate > $T)
RETURN a, r, b

This produces an accurate, complete view of the graph at time T.

6. Go + Neo4j Driver Pseudo-code

Below is idiomatic Go pseudocode demonstrating versioned ingestion logic.

6.1 Creating/Updating a Node

func ingestNode(id string, props map[string]interface{}, processDate time.Time) {
    session := driver.NewSession(neo4j.SessionConfig{AccessMode: neo4j.AccessModeWrite})
    defer session.Close()

    _, err := session.WriteTransaction(func(tx neo4j.Transaction) (interface{}, error) {
        params := map[string]interface{}{
            "id":          id,
            "processDate": processDate,
            "props":       props,
        }

        query := `
            MERGE (n:Entity {Id: $id})
            ON MATCH SET 
                n.lastUpdated = $processDate
            ON CREATE SET 
                n.StartDate = $processDate,
                n.lastUpdated = $processDate,
                n += $props
        `
        return tx.Run(query, params)
    })
    if err != nil {
        log.Fatal(err)
    }
}

6.2 Closing Stale Nodes

func closeStaleNodes(processDate time.Time) {
    session := driver.NewSession(neo4j.SessionConfig{AccessMode: neo4j.AccessModeWrite})
    defer session.Close()

    _, err := session.Run(`
        MATCH (n:Entity)
        WHERE n.lastUpdated <> $processDate AND NOT n:Deleted
        SET n.EndDate = $processDate, n:Deleted
    `, map[string]interface{}{
        "processDate": processDate,
    })
    if err != nil {
        log.Fatal(err)
    }
}

7. Common Pitfalls & How This Model Solves Them

7.1 MERGE cannot match on NULL

Many developers attempt:

MERGE (a)-[r:LINK {EndDate: NULL}]->(b)

This does not work in Neo4j.

Solution:
Use Status for deterministic relationship merging.

7.2 Avoid overwriting nodes

You never update older versions.
Instead:

Close old version (EndDate, :Deleted)
Create new version

This preserves full history.

7.3 Efficient current-state filtering

Instead of comparing timestamps, we rely on:

NOT n:Deleted
r.Status = "Active"

These are extremely fast and index-friendly.

8. Performance Considerations

Indexes

You should index:

Node: Entity(Id)
Node: Entity(Deleted)
Rel: LINK(Id)
Rel: LINK(Status)

Batching

Batching ingestion improves performance substantially.

Avoiding deep history scans

Historical reconstruction always uses date filtering, not traversal of version chains.

9. Summary of the Model

Nodes:
- Id
- StartDate
- EndDate
- lastUpdated
- :Deleted label

Relationships:
- Id
- StartDate
- EndDate
- Status ("Active"/"Deleted")
- lastUpdated

Ingestion phases:

1. Node ingest
2. Relationship ingest
3. Close stale versions

Key benefits:

Clean, fast “current” queries
Complete historical accuracy
Deterministic version merging
No risk of MERGE-on-NULL issues
Proven scalability

10. Conclusion

Temporal versioning in Neo4j is not just a schema change—it is an architectural decision that affects ingestion pipelines, storage models, and query semantics.
The strategy described above enables:

Efficient ingestion without overwriting data
Simple current-state queries
Accurate time-travel analysis
Clean separation of active vs. historical data
A scalable, deterministic versioning model

This design supports both high-performance applications and advanced tooling such as diffing, history exploration, and lineage tracking.

If you are building any graph system where state changes matter, this approach provides a strong, production-grade foundation for temporal graph modeling.

[Boost]

Satyam Shree — Tue, 11 Nov 2025 04:15:57 +0000

Building a Mini Kafka in Go — My Journey Creating go-pub-sub

Satyam Shree ・ Nov 10

#go #grpc #pubsub #kafka

Building a Mini Kafka in Go — My Journey Creating go-pub-sub

Satyam Shree — Mon, 10 Nov 2025 13:15:03 +0000

🌀 Building a Mini Kafka in Go — My Journey Creating `go-pub-sub`

A hands-on dive into distributed messaging, gRPC streams, and pluggable storage — all in Go.

👋 Intro

Over the past few weeks, I’ve been exploring how systems like Kafka and Pulsar handle messaging, partitioning, and consumer groups. Instead of just reading papers, I wanted to build one myself — from scratch — to truly understand how Pub/Sub systems work under the hood.

That’s how go-pub-sub was born — a lightweight, gRPC-based Publish–Subscribe broker written entirely in Go.

It started as a learning project but grew into a deployable, extensible system that can run locally or in containers.

⚙️ What is `go-pub-sub`?

go-pub-sub is a mini distributed broker that lets you:

Publish messages over gRPC
Stream them to consumers (with acknowledgments)
Organize them by topics, partitions, and consumer groups
Plug in different storage layers — in-memory, Redis, or Postgres
Expose Admin APIs to manage topics dynamically

It’s meant to be small, clear, and hackable — a Kafka-like learning platform.

🧩 Architecture Overview

Publisher(s) → gRPC (Publish)
Consumer(s)  ← gRPC Stream (Subscribe)
↳ Ack → gRPC (Ack)
↳ Admin APIs → CreateTopic, ListTopics, TopicInfo

The broker exposes two main services:

PubSub — handles Publish, Subscribe, Ack
Admin — topic creation, inspection, listing

Internally, the broker consists of:

Broker layer → core logic for pub/sub, offsets, consumer groups
Storage layer → in-memory / Redis / Postgres adapters
Middleware → logging, recovery, optional auth
Config layer → YAML-based configuration
Clients → simple Go-based producer and consumer binaries

💡 Why I Built It

Like most Go devs, I’d read about channels, goroutines, and concurrency patterns — but hadn’t seen them used in distributed systems.

Building a Pub/Sub broker was the perfect playground:

gRPC streams → long-lived connections
Consumer groups → concurrency and coordination
Storage adapters → interfaces and dependency inversion
Message acknowledgment → reliable delivery patterns
Docker-based testing → reproducibility

And honestly, nothing teaches you distributed thinking like debugging your own broker 😅.

🧱 Core Design Concepts

Topics and Partitions

Each topic is split into one or more partitions for parallelism.

Messages are appended to a partition and assigned an incremental offset.

Consumer Groups

Multiple consumers in the same group share partitions.

Each group tracks committed offsets per partition, ensuring at-least-once delivery.

Storage Backends

Memory: great for tests and local development
Redis: fast ephemeral storage (supports consumer state tracking)
Postgres: durable persistence with offset commits and retention

🧰 Running It

1️⃣ Run the broker (in-memory)

go run ./cmd/server --config=config/config.yaml

2️⃣ Start a consumer

go run ./client/consumer --addr=localhost:50051 --topic=events --group=g1

3️⃣ Publish messages

go run ./client/producer --addr=localhost:50051 --topic=events --msg="hello world"

Output:

INFO  2025/11/10 22:31:12 📤 published topic=events partition=0 offset=42
INFO  2025/11/10 22:31:12 ➡ received topic=events partition=0 offset=42 value=hello world
INFO  2025/11/10 22:31:12 ✅ acked offset=42

🧪 Smoke Testing (Docker Style)

I wrote a full bash smoke test that spins up a broker container, waits for readiness using logs, and runs a real consumer + producer pair locally.

./scripts/smoke_with_docker.sh -n 100 -i go-pub-sub:local -p 50051

It verifies that all messages are received and acknowledged, even across partitioned topics.

When it prints ✅ SUCCESS, you know your broker is behaving like a pro.

🗄️ Production-Ready Direction

Right now, go-pub-sub supports three storage types:
| Backend | Type | Use Case |
|----------|------|----------|
| memory | In-memory | Fast testing |
| redis | Ephemeral | Temporary persistence |
| postgres | Durable | Production use |

I’m currently building a Postgres-backed store that supports:

atomic offset assignment via SQL sequences
durable message and offset persistence
configurable retention cleanup
per-topic partition tables for scalability

This will make the broker durable and crash-safe while keeping it minimal.

🔍 Lessons Learned

gRPC streams are powerful but tricky — they demand careful connection management.
Consumer group coordination can get complex even with small datasets.
Interfaces are your friend — swapping backends was easy once interfaces were clean.
Dockerized smoke testing saved hours of debugging inconsistencies.
Go’s concurrency model shines for pub/sub patterns.

🚀 What’s Next

🗄️ Complete Postgres backend (durable persistence)
🔎 Add /health and /metrics endpoints
🧹 Implement retention cleanup goroutine
🌐 Add gRPC-Web / WebSocket gateway for browser-based apps
🧰 Build a simple chat app demo using go-pub-sub as backend

📚 Tech Stack

Language: Go 1.25
Transport: gRPC
Storage: In-memory / Redis / Postgres
Orchestration: Docker Compose
Testing: grpcurl, smoke scripts, Go integration tests

💬 Wrap-up

go-pub-sub started as a weekend curiosity and ended up teaching me more about distributed coordination than any book could.

It’s small, educational, and — with Postgres — production-capable for internal systems or side projects.

If you’re learning gRPC, Go interfaces, or concurrency patterns, this is one of those projects that will click everything into place.

🧠 Repo: github.com/satya-sudo/go-pub-sub

📦 Docker image (coming soon): docker pull satya-sudo/go-pub-sub

Built with ❤️ in Go — because understanding systems is better than just using them.

💡 Tags

#go #grpc #opensource #pubsub

If you’ve ever wanted to understand Kafka’s internals by building one, check out the repo and try running the smoke test!

Drop your thoughts, feature ideas, or PRs in the comments 👇

Sometimes small ideas teach you the biggest lessons.

Satyam Shree — Sat, 25 Oct 2025 04:45:21 +0000

🧠 Go-URL: Building a Lightweight, Scalable URL Shortener in Go

Sometimes small projects end up teaching you the biggest lessons.

Go-URL started as a simple weekend idea — “let’s build a basic URL shortener in Go.”

But as I started designing it, I realized it was a perfect opportunity to explore system design, caching, persistence, and scalability — all within a compact, real-world problem space.

🚀 The Idea

The goal was simple:

Build a fast, reliable URL shortener with:

Clean architecture
Stateless services
High scalability
Low latency

And do it all using technologies I love working with: Go, Redis, PostgreSQL, and Kubernetes.

⚙️ Tech Stack Overview

Component	Purpose
Go (Golang)	Core backend logic, API server, concurrency handling
Redis	Fast caching for redirect lookups
PostgreSQL	Persistent storage for original and shortened URLs
Kubernetes	Deployment, load balancing, auto-scaling
Docker	Containerization for portability

🧩 System Design

1. Stateless API Layer

The API is built using Go’s net/http package and structured around clean architecture principles — keeping business logic, repository layers, and handlers decoupled.

This design allows horizontal scaling — multiple instances can run behind a load balancer with no shared state.

2. Redis for Speed

URL redirection is read-heavy.

Instead of querying PostgreSQL for every hit, Redis caches the mappings:

short_url -> original_url

Whenever a new short URL is created, it’s stored in both Redis and PostgreSQL.

On lookups, if Redis misses, the record is fetched from the DB and re-cached — a classic read-through caching pattern.

3. PostgreSQL for Durability

Redis is blazing fast but volatile.

To ensure persistence, PostgreSQL stores all URL mappings permanently, complete with timestamps and access logs.

A background worker syncs write operations asynchronously to maintain API responsiveness.

4. Kubernetes for Scalability

I containerized the service with Docker and deployed it on Kubernetes.

K8s handles:

Load balancing across pods
Auto-scaling based on CPU/memory metrics
Rolling updates without downtime

This setup ensures Go-URL can handle sudden traffic spikes smoothly.

🧠 Key Challenges and Learnings

Balancing cache and consistency

Designing the Redis sync flow without introducing stale data was tricky. A hybrid TTL-based strategy worked best.
Async syncs without blocking requests

I built a simple worker queue in Go to offload DB writes, improving response times significantly.
Observability

Added basic logging and metrics using Go’s expvar and structured logs — it helped a lot during debugging and load testing.
Scaling on Kubernetes

Watching pods auto-scale under simulated load was incredibly satisfying — a real-world validation of clean design.

💡 Performance Results

After load testing with hey and wrk, the results were impressive:

Median response time: <10ms (with Redis warm)
Sustained 10K+ RPS across multiple instances
Zero downtime during redeployments via Kubernetes rolling updates

✨ What I Took Away

Go-URL reminded me that even the simplest systems can be architecturally deep if you think about them right.

It taught me:

How clean architecture helps with maintainability.
Why caching layers are crucial for scalability.
How Kubernetes orchestration simplifies deployment complexity.
And most importantly — how small design decisions impact performance at scale.

🔗 Check it Out

You can explore the project here:

👉 GitHub: Go-URL

If you’re into backend systems, Go, or distributed design — I’d love to hear how you would scale or extend this system further.

DEV Community: Satyam Shree

[Boost]

I Built My Own Local-First AI Assistant in Go — Meet Nox

I Built My Own Local-First AI Assistant in Go — Meet Nox

What is Nox?

The Architecture

Why Go?

The LLM Shouldn't Handle Everything

Giving an LLM Access to Your Computer Is Slightly Terrifying

Local Speech Recognition with Whisper

Running the Brain Locally

Browser Automation Without Giving AI the Browser

Home Automation

Email — But Intentionally Read Only

Timers That Survive Restarts

Local-First Doesn't Mean "Never Use the Internet"

Running Nox

What I'm Building Toward

One Thing This Project Changed My Mind About

I Built Tic-Tac-Toe the Old Way — Before Coding Agents

What I did.

The final result

Why Tic-Tac-Toe?

Starting with the simplest model

The GameManager

Then came HTTP

Designing the game rules

Then I wanted real-time updates

Understanding WebSockets instead of just using them

ConnectionManager

any or a common WebSocket message?

The architecture started to emerge

Things that broke

What I learned about Go

net/http

Structs and composition

Errors

Maps

Pointers

Concurrency

Why I didn't use a coding agent

The uncomfortable part of building without an agent

What I would change next

Persistence

Authentication

Reconnection

Concurrency

WebSocket lifecycle

Tests

What started as Tic-Tac-Toe

Final thought

[Boost]

I Got Tired of Rewriting Segment Trees in Go... So I Published One

I Got Tired of Rewriting Segment Trees in Go... So I Published One

Why?

Design Goals

Typical Operations

Why publish it?

Repository

A Practical Guide to Temporal Versioning in Neo4j: Nodes, Relationships, and Historical Graph Reconstruction

1. Design Goals

1.1 Minimal disruption to existing queries

1.2 Complete bitemporal representation

1.3 Deterministic version merging

1.4 Efficient deletion detection

1.5 Neo4j MERGE limitations must be respected

2. Data Model

2.1 Versioned Nodes

ASCII Diagram

2.2 Versioned Relationships

Why we need Status

3. Ingestion Architecture (Multi-Phase)

3.1 Phase 1 — Node Ingestion

Cypher (simplified)

3.2 Phase 2 — Relationship Ingestion

3.3 Phase 3 — Version Closure (Deletion Detection)

4. Querying the Current Graph

Nodes

Relationships

5. Querying Historical Snapshots

`any` or a common WebSocket message?

`net/http`

Why we need `Status`

🌀 Building a Mini Kafka in Go — My Journey Creating `go-pub-sub`

⚙️ What is `go-pub-sub`?