I was wrong.

The behaviour of the system’s surfaces - the UI, auth layer, and OpenAI provider - revealed the real rules the schema needed to uphold long before any abstract modelling exercise could.

Surfaces are the concrete touchpoints you can actually see and test. They expose real behaviour and constraints, which makes them a far more reliable foundation for modelling than guessing at tables.

This post is a case study in how a surface-first approach helped me design a smaller, clearer, more reliable schema that matched the product instead of my assumptions.

1. The Problem I Needed to Solve

LittleSteps AI had to support:

• authenticated Google users

• persistent chat threads

• ordered messages

• thread/URL navigation

• OpenAI-powered prompts and responses

Core problem: The real difficulty wasn’t building a chat UI - it was deciding what a minimal schema looked like, and whether the backend or frontend should drive the design.

As I was thinking about schemas (and feeling a little lost), two things became clearer when I mapped user flows and built a quick minimal frontend:

• (1) The user experience had a fixed shape: A predictable flow: sidebar → thread list → thread rename → message list → new message appended.

• (2) The behaviour of the UI wasn’t optional: It imposed concrete rules the backend had to respect: Those behavioural constraints turned out to be far more informative than starting with tables and guessing relationships.

• (3) The model provider exposed strict sequencing and message structure:

  The OpenAI request–response cycle surfaced rules around ordering, role classification, and token metadata - constraints that the schema would eventually need to include.

• (4) The auth layer brought its own structural boundaries:

  BetterAuth came with a working user/session/account schema and strict ownership hierarchies. Instead of reinventing identity, these boundaries became another “surface” that shaped the final data model.

By mapping early UI flows and observing the behaviour of the auth layer and model provider, the actual ‘surfaces’ of the system became clear.

2. Constraints: What Made This Non-Trivial

The behaviour of the UI, the auth layer, and the OpenAI provider surfaced constraints that the schema had to include:

• Deterministic ordering
  Messages must appear exactly in the order the user expects - no races, no timestamp drift.

• Non-guessable identifiers
  Thread IDs appear in the browser URL and must be safe to share.

• Strict ownership
  Only the creator of a thread should ever access it.

• No orphaned entities
  A thread delete should cascade messages; a message must never “float”.

• GDPR-aligned deletion
  Removing a user should remove data across auth sessions, accounts, threads, and messages.

• Room for growth without premature complexity
  Token usage, analytics, or rate limits might come later-but shouldn’t distort the minimal model now.

• Atomic prompt–response cycles
  Each user prompt produces a tightly coupled pair of messages (user → assistant), which must be persisted together in the correct order.

Together, these constraints narrowed the viable designs. Once the rules were visible, only a small, clean schema actually fit them.

3. Why Surface-First (Not Schema-First) Led to a Better Model

My core insight wasn’t “UI-first”.

It was surface-first: using the concrete surfaces of the system (UI, auth layer, and model provider etc) to reveal the concrete behaviours and rules the schema must design for.

To do that, my mental model is:

Surface → Rules → Schema

(Surface (behaviours) → Rules (invariants) → Schema)

This model works because the behaviour of a system’s surfaces always constrains what the schema must guarantee.

The behavioural inputs came from three places:

a) The UI

• What does the sidebar need to load?

• How must threads appear in order?

• How do we navigate after creating a new message?

• Where does rename write to?

b) The OpenAI model provider
Its request-response cycle surfaces constraints around:

• atomic prompt+response writes

• message role classification

• token metadata

• error handling paths

c) The auth layer (BetterAuth)
It defines ownership, session guarantees, and the edges of who can access what.

What this revealed

Answering those questions produced a set of invariants:

• Threads belong to exactly one user

• Messages belong to exactly one thread

• Messages require stable ordering

• Thread titles must be constrained

• URLs must use non-enumerable IDs

• Delete-user must delete everything cleanly

Once the invariants were clear, the schema became straightforward to design.

Why I didn’t start with schema-first

Schema-first would have forced:

• guessing relationships before understanding flows

• modelling features that didn’t exist

• encoding constraints that didn’t reflect behaviour

• hiding edge cases the UI and provider would later surface

Schema-first is low resolution-it shows what entities might exist, but it doesn’t show how they behave.

Surface-first revealed the dynamics that the schema needed to preserve.

Each surface exposed a different part of the real behaviour: the UI revealed navigation and ordering, the model provider revealed atomic cycles, and the auth layer revealed ownership boundaries.

4. The Data Model

Combining UI flow, auth guarantees, and OpenAI’s request–response lifecycle, the schema settled into four tables:

Each part of the schema maps directly back to the constraints surfaced earlier. The UI revealed ordering and navigation behaviour, which drove the need for explicit sequences and non‑enumerable IDs. The model provider revealed atomic prompt–response cycles and role structures, which shaped the message table. The auth layer exposed strict ownership boundaries, which defined the thread → user relationship and cascade rules. By tying each schema choice to a rule revealed by a surface, the final model became smaller, more explicit, and directly aligned with real product behaviour.

User, Session/Account, Thread, Message.

User (id TEXT PK, email UNIQUE, name, createdAt, updatedAt)
 ├─ Session (id TEXT PK, token UNIQUE, expiresAt, userId FK → User.id ON DELETE CASCADE)
 ├─ Account (id TEXT PK, accountId, providerId, userId FK → User.id ON DELETE CASCADE)
 └─ Thread (id UUID PK, userId FK → User.id ON DELETE CASCADE, title VARCHAR(60), createdAt, updatedAt)
     └─ Message (id UUID PK, threadId FK → Thread.id ON DELETE CASCADE,
                 sequence INT, role ENUM[system|user|assistant], content TEXT,
                 createdAt, promptTokens?, completionTokens?, totalTokens?,
                 UNIQUE(threadId, sequence))

What This Structure Guarantees

1. Clear ownership

A single userId foreign key on Thread encodes all access rules.
The API only needs one join to enforce permissions. This directly satisfies the ownership boundaries revealed by the auth surface.

2. No orphaned data

ON DELETE CASCADE removes dependent rows automatically.
This makes GDPR “delete my data” flows trivial. This addresses the data‑lifecycle rules exposed by both the UI surface and GDPR deletion requirements.

3. Deterministic message ordering

Timestamps are unreliable under async workloads and parallel writes.
Instead, the schema uses:

• a single source of truth: sequence

• DB-level protection: UNIQUE(threadId, sequence)

This guarantees consistent ordering for:

• UI rendering

• API consumers

• DB-backed tests (Vitest)

• debugging race conditions

Deterministic ordering emerged as a key requirement from several surfaces. I hadn’t anticipated it early on, but it became clear very quickly that relying on timestamps would produce inconsistencies. This solves the ordering and atomicity constraints exposed by both the UI and the model‑provider surfaces.

4. Safe URLs

UUIDs make thread/message identifiers:

• non-enumerable

• shareable

• URL-safe

• predictable in routing

No need for obfuscation or extra indirection. This satisfies the routing and non‑enumerability requirements imposed by the UI surface.

5. Practical constraints exposed by the UI surface

The UI forced the schema to adopt:

• title length limits

• stable sequence ordering

• UUID routing

• role validation (system | user | assistant)

Every constraint is tied to real behaviour-not speculation. These schema constraints originate directly from the behavioural limits surfaced in the UI.

5. Trade-offs I Made to Ship Faster

• 1. Some rules (invariants) live in app logic, not the DB
  Ownership checks and sequence assignment happen in the application layer.
  This keeps the schema simple but shifts responsibility to well-tested code.

• 2. Single-user threads only
  Supporting shared threads would require membership tables and more complex ACLs.
  Out of scope for MVP - so the model stayed intentionally simple.

• 3. No configurable system prompts yet
  I excluded per-thread system messages; future UX changes will require schema migrations.
  This avoided premature abstraction.

• 4. Shared Postgres instance during tests
  Vitest runs tests concurrently, so I used one Postgres container for all tests.
  DB-backed tests validated:

  • thread creation

  • message append

  • ordering guarantees

  • deletion behaviour

Per-test isolated DBs would reduce async testing bugs and improve test isolation - but at the cost of slower iteration. I chose a shared database first to keep feedback loops fast.

• 5. MVP focus over performance/security
  I explicitly avoided deep optimisation or hardening (RLS, rate-limits, encryption, extra indexes) until the product stabilises.

6. Closing Thoughts: Surface-First Schema Design

The biggest lesson from LittleSteps was clear:

Schema design becomes clearer when you start from real behaviour, not tables.

By grounding everything in UI flows, auth rules, and provider interactions, the backend became:

• smaller and more explicit

• easier to reason about

• easier to test

• aligned with real product constraints

• capable of evolving without rewrites

The process wasn’t “UI-first” so much as surface-first - starting from the external surfaces of the system to understand the rules it must uphold.

I appreciate this is more difficult in a production system with large volumes of existing data, but for early product stages it enables fast iteration and clearer modelling.

If you’re building a full-stack app - especially one for quick prototypes / fast itteration / with chat-like interactions / LLM workflows - try this pattern:

Surface → Rules → Schema

Model the real flows first.
Let the schema fall out of them.
You may find that the architecture becomes simpler, more reliable, and easier to extend.

If we become deluded, we get blind spots and we can miss the things that will sink us.

For me personally this is why one of the most important principles of the Agile manifesto is “At regular intervals, the team reflects on how to become more effective, then tunes and adjusts its behaviour accordingly.”

Second to that it is: “the Art of maximising work NOT done" read more.

Feedback, retrospectives, iterating the scope is key. This applies in my technical solo projects, my team projects and in life.

You’re not delusional when you’re wrong.

You’re delusional when you don’t test if you’re wrong.

Build a small, meaningful part — get feedback — adjust.

Agile has become such a buzzword and a certified set of mindless rigid processes I feel the intent of agile is often lost in the processes.

I think we need to get back to the intent, and less of the performance.

What’s your favourite Agile principle? Why?

“Coding is execution. Engineering is understanding.”
I didn’t realise the difference — until I paused the build to map the architecture.

Why I Had to Stop Before I Even Started

I sat down to begin building the first slice of my new project — a simple LLM app for parents — and... roadblock time 😬

It wasn’t a motivation issue. I had a good sense of what the app should do and a rough stack in mind: Next.js, Drizzle, OpenAI, Zod, OAuth. But something felt off.

The problem, I realised, wasn’t that I didn’t know how to code — it was that I didn’t know how it all fit together. I couldn’t see the shape of the system I was trying to build. And without that, I didn’t know how to start, or how to be confident in my stack and what I was building.

So I paused.

Before jumping into code, I decided I needed to understand the architecture — the flow, the boundaries, the responsibilities. I didn’t want to just write code. I wanted to understand how the system worked.

This post is a reflection on what I did, what I learned, and why this was one of the most important early steps I’ve taken in learning to think like a full-stack engineer.

Why I Paused: I Had(ish) the Tech Stack — But Not the System

I’d already chosen my stack. I had a rough idea of the libraries I planned to use. But I didn’t fully understand how they fit together — or what each one was responsible for.

I couldn’t break my work down into slices see my post on Minimum Viable Slice because I couldn’t tell where one concern ended and another began. Was this part of the UI? The backend? Should I validate input in the handler or the service? I didn’t know — and it made every step feel uncertain.

It felt like having pieces of a jigsaw without the picture on the front of the box to guide me.

Pausing to think about the system helped me:

• Clarify what was actually in my tech stack — and what purpose each piece served

• Understand how tools like Zod, JWT, and Drizzle mapped onto architectural concerns like validation, auth, and persistence

• Iterate more confidently on my scope and design — because I now had somewhere to put things

What I Did: Creating a Mental Model of My Application

The first thing I did was map out the major concerns: UI, API, validation, authentication, business logic, persistence.

Then I walked through a single flow: a user submits a prompt. What happens from there?

I traced the data as it moved from the frontend, through the route handler, into validation, through services, to the database, and back.

This is how I thought about concerns, components, and responsibilities:

• What are the main concerns (broad areas of responsibility)?

• What are the main components (things that fulfil those concerns)?

• What are their responsibilities (the job they do)?

Here's what I came up with:

This helped me understand not just what tools I had, but why each one existed and what part of the system it served.

By following the flow through the system, I started to see that architecture wasn’t abstract or static — it was dynamic and revealing. I began to notice gaps, assumptions, and flaws in my knowledge.

This wasn’t just an academic exercise. It helped me understand:

• What a “concern” really is, and how to separate them

• The difference between a domain (like "auth") and a component (like AuthForm.tsx)

• What boundaries exist in my system — and why those boundaries matter

Up until then, architecture felt like a checkbox — something you’re told to sketch out at the start of a project, but not something grounded in understanding or learning. Then I came across Martin Fowler’s definition of architecture as a 'shared understanding of the system’s design' — and things clicked. In this case, the shared understanding was just between me and myself — but that alone was transformative.

“Architecture is the shared understanding of the system's design.” — Martin Fowler

What I Learned: From Vague Tools to Clear Responsibilities

Once I saw how the system worked, I started to understand where each tool fit — and why it was there.

For example:

• Zod: a runtime validator that ensures incoming data (like API requests) matches the expected shape. While TypeScript interfaces define static types at compile time, Zod performs validation at runtime — so your app can safely use the data it receives.

• TypeScript interfaces: static contracts that describe the expected shape of data. They help during development but aren't enforced at runtime.

• JWT: a signed token (not middleware itself) that acts like a passport — proving the user's identity and authorisation. It's typically verified by auth middleware, which allows or blocks access to protected routes and services.

• Drizzle ORM: a type-safe way to define your database schema and query your DB in TypeScript — removing the need for raw SQL in most cases.

I stopped seeing tools as magic boxes. I started seeing them as components in a larger system — each with a role and a place.

This also exposed gaps. For example, I realised I didn’t fully understand how OAuth and JWT worked together. But now that I knew where in the flow that gap lived, I could go learn it in context.

And that’s the difference. I wasn’t just Googling things — I was learning how they fit.

Why It Helped: I Can Now Approach the Build with more Confidence

I haven’t written the core feature code yet — but I now know what I’m building, how I can approach the design, and how to break it down into smaller, logical parts using my Minimum Viable Slice plan.

The architecture will evolve — and that’s fine. But now:

• I understand where different types of logic belong

• I know what my first slice should include

• I can scope, plan, and test without guessing

• And when something breaks later, I’ll have a better idea of where in the system to look

This isn’t about perfection. It’s about moving from fog to flow — slowly, but intentionally.

Is This Overthinking or Useful?

Honestly, I worried I might be overthinking it. Shouldn’t I just be building things and figuring it out as I go?

But over time, I’ve come to see that this is part of building. Designing isn’t procrastination — it’s what gives the build direction.

Having a rough architectural map gave me clarity, helped me learn more deeply, and will save me time and confusion later. Especially as a junior developer, this kind of deliberate thinking can be a force multiplier.

Even now, I may still get stuck — but I’ll be stuck in a known place, not lost in a maze.

Advice to Other Juniors: Map Before You Build

If you're starting a project and feel stuck, try stepping back.

Ask yourself:

• How does a request move through your system?

• What part handles validation?

• What’s responsible for business logic?

• Where should this data end up?

Drawing a rough architecture diagram, walking through a single flow, and identifying where each tool or function lives can be a huge unlock.

These diagrams don’t need to be perfect or pretty — they just need to help you reason through what you're building.

Still not sure whether your planning is helpful or just a detour? Here’s a quick test I found useful:

This helped me validate that I wasn’t just stalling — I was preparing to build well.

You don’t need to be an architect to think architecturally. You just need to care how your system fits together.

Final Thoughts

This reflection doesn’t mean I’ve figured it all out — far from it.

But it was the first time I stopped just writing code, and started thinking like an engineer.
Building moved beyond just code.

Looking ahead, as AI becomes more integrated into our day-to-day tools, I think we’ll need to be less like coders, and more like engineers — even at a junior level.

And right now, using system design and architecture to uncover gaps in my knowledge and build with more intent feels like the right next step.

For me, that shift made all the difference.

What’s Next?

I’ll use this blog to share what I’m learning, document side projects, reflect on my journey into software engineering and to share my thoughts on the industry.

You can sign up for email updates here, follow my GitHub, or connect with me on Linkedin as I build stuff 🙂

Dileepa Ranawake is a full-stack software engineer, accessibility advocate, and former startup co-founder. He’s exploring how AI, accessibility, and engineering can come together to build tech-for-good.

That was where I was at, in and during my Jammming project on my GitHub. I knew what I wanted to build but once I got into the code, it all started to unravel. I jumped between components. Refactored things I hadn’t even finished. Tried to connect backend endpoints before the frontend was working. It became chaotic, and became slow. Bugs were hard to track. I didn't know where to begin. In the build phase it was all a bit chaotic. In fairness to myself, I was figuring out react, but it got me thinking about how I'd approach the process in the future.

With my background in startups / being a product manager I'm familiar (like you probably are) with agile methodology, the learn Build-Measure-Learn cycle. In particular I was used to thinking about an MVP in desiging products.

But when it came to building, MVP thinking didn’t help. It told me to build a "skateboard before the car"—but how does that translate to actual code how we tackle a project? If you're not super geared up with design patterns and architecture it's quite difficult to usefully break down an MVP.

If you're in product you're probably familiar with the challenge of measuring meaningful progress without bugging your engineers. With my engineer hat on, the limits of MVPs are clear.

To overcome the where can I start problem, In this post, I’ll share the idea of the Minimum Viable Slice—a small, deployable, technically complete unit of functionality that helped me break through that builder’s block and start making confident progress.

The Problem with MVP Thinking

We’ve all heard it: start with the simplest version of your product. And yes, Minimum Viable Product (MVP) thinking is great from a business and user perspective. But when you're the one writing the code, “simplest product” doesn’t always give you a clear place to start.

In practice, it left me floundering. What should I code first? Should I build the UI? The database? Some mocked-up flow?

What ended up happening was:

• I jumped between frontend and backend
• I introduced bugs by half-implementing features
• I rewrote logic as the scope shifted
• I found it hard to test anything in isolation

The result was a messy codebase, lots of rewrites, and slow progress.

What Is a Minimum Viable Slice?

A Minimum Viable Slice (MVS) is my antidote to MVP ambiguity. It’s a narrow, technical-first way to scope and build your project incrementally.

Here’s how I define a slice:

• Mergeable – a slice can be safely merged into main without breaking the system
• Testable – its core function can be verified (input → output) through tests or basic interaction
• Functional – it delivers a clear technical goal (e.g. auth, persistence, or an API integration)

A slice can be designed to be mergeable to main, deployable to a staging environment, or even production-ready—depending on your goal. The point is that it’s internally stable and complete, even if it’s not yet user-facing. Ultimately, I think of MVS as more of a guiding principle than a rigid set of rules.

It’s not style-focused. It does not need to be user-facing. It’s not concerned with polish.

The focus is just something that's technically functional and deployable,

Each slice stands on its own and pushes your architecture and build forward.

How MVS Helped Me Scope My LLM App

After the Jammming experience, I wanted to address some of the builders block / pitfalls in my next project - a full-stack LLM app.

Whereas in Jammming I did a sketch and went all out, I decided to create a hybrid scope / technical design document.

In the technical scope defined my requirements, problem etc and then I broke the app down into slices. It's still a work in progress and this post is reflecting on my learnings / things and research but at time of writing, at a high level it looked like this:

1. Basic LLM Prompt Loop (No Auth) - Set up a functional prompt → response loop using the OpenAI API, in a Dockerized full-stack app.
2. User Authentication - Introduce user authentication to enable personalised features and secure user-specific routes in later phases.
3. Prompt History & Persistence - Add database-backed storage of user prompts and LLM responses, enabling a personal history view for logged-in users.
4. Milestone Guidance via System Prompting - Use system prompts to generate simple milestone guidance based on prior user input, without external knowledge grounding.

Each slice was designed to be technically complete enough to be merged and tested as part of the main project. For example, I could implement and validate the LLM prompt loop without needing auth or persistence yet. The slices aren't standalone services—they’re functional steps that fit together into a cohesive build.

This way, I could:

• Make real progress (each slice was visible and testable)
• Focus on technical design early
• Avoid rewrites by building modularly
• Keep motivation high (tiny wins add up!)

I’ll try to share a snapshot of my slice plan once I publish the repo.

MVS vs Vertical Slice Architecture vs MVP

You might be thinking: isn't this just vertical slice architecture?

Sort of — but with a twist.

Common Pitfalls to Avoid

• Tightly Coupled Slices: If one slice breaks when another changes, it defeats the point of isolating functionality.
• Vague Interfaces: Without clear input/output definitions, later slices may cause conflicts or rewrites.
• Backend Bias: It’s tempting to over-focus on infrastructure. Include minimal UI views early to maintain usability context.
• Skipping Tests: Tests give you confidence that each slice is safe to merge. Even basic checks help.
• Endless Refactoring: Log ideas for improvements, but move forward slice by slice. Avoid reworking every layer with each new addition.

MVS is about building up the infrastructure and logic before focusing on polished, user-facing experiences.

It gives you a structure to think and build incrementally—even when you're working solo or figuring things out as you go.

When to Use It and How to Start

I’ve found MVS especially helpful in these scenarios:

• Building side projects or learning apps
• Rapid prototyping (e.g. hackathons)
• Scoping complex systems without overwhelm
• Feeling builders block at the start of a project

Here’s how I recommend getting started:

1. Define the core purpose of your project
2. Write down the technical concerns or building blocks
3. Break those into “slices” that can be isolated and deployed - try and design slices so that minimal refactoring is required for subsequent slices.
4. Order them logically—start with what other pieces depend on - this informs your architecture and details.
5. Deploy and test each slice before moving on

This shifts your thinking from “what features do I need?” to “what system pieces do I need to see working?” Another way of thinking about it is you are building internal features / system features.

Lessons Learned and What’s Next

Since using this approach, I’ve felt more clarity and less frustration in starting a project / planning.

This has also got me thinking more about interface design, and the gaps in my knowledge there. I might do a deep dive onto interface design later / share my learnings.

I’m currently using this method to guide my LLM web app build—and I’ll be publishing the full project, plan soon.

I'll test this approach, so if I find issues with this approach I'll try write about it and share my learnings... stay tuned for updates!

Summary

A Minimum Viable Slice doesn’t replace MVP or vertical slice architecture— it complements them. It gives you a practical way to start building things without getting overwhelmed.

It’s deployable, testable, and keeps your project moving.

It gives you a way to break things up logically.

Have you tried scoping your projects like this?

Connect with me on LinkedIn or check out my GitHub. I’d love to hear how you approach scoping and breaking down projects and thinking about architecture and design.

What’s Next?

I’ll use this blog to share what I’m learning, document side projects, reflect on my journey into software engineering and to share my thoughts on the industry.

You can sign up for email updates here or follow my GitHub as I build stuff 🙂

As my career in software engineering evolves, I wanted a space to:

• Share learnings.
• Reflect on my side projects.
• Share my industry thoughts and views.
• Build out my profile.
• Low cost / free.

I already had a Substack, but hadn’t used it much and it was a bit unfocused (I started my substack a year ish ago as a kind of catch all blog to share broad thoughts).

It was easy to get started on Substack, but I found its push toward monetisation a bit off-putting (I don’t want to paywall my content). I wanted a clean, developer-focused blog, without aggressive paywalls and email capture and a bit more customisability.

So I started exploring other options...

Considering Static Sites and GitHub Pages

I wanted to keep it simple, and keep it low cost! A static site hosted via GitHub Pages is free, fast, and version-controlled.

After a bit of searching I found Bootstrap and found a lot of nice, free templates, and started tinkering...

What I liked:

• Simple to set up
• Great for a no-frills landing page
• Loads of community templates

What I didn’t:

• I could see routing and organising posts becoming a pain quickly.
• Didn't want to spend time writing boilerplate or patching together workarounds.
• I could see it as easy to outgrow for more complex content e.g filtering tags, components, routing etc.

This made me stop and ask: what do I really need?

Step 2: Defining My Requirements

Roughly, I needed:

• A standard blog layout (posts, tags, nav)
• Markdown support
• Easy updates and routing
• Custom domain
• Low or no cost

I didn’t want to spend too much time maintaining infrastructure, but something a bit more powerful and flexible, that could accommodate more complex and dynamic elements

Step 3: Trying Astro

Astro caught my eye. It’s lightweight, fast, and developer-friendly. I built a minimal Astro blog, deployed it via GitHub Pages using GitHub Actions. Quite fun. Easy. I avoided something like Next.js + Vercel - simply for cost and rendering speed (and maybe I was a little lured by new and shiny)...

I built a little Astro blog (not a looker!) to familiarise myself with the framework, test out GitHub actions and deploy to pages and Astro basics. You can see my GitRepo here and the live site here. If it was my main production site I'd have started with their free templates, to avoid wasting time on styling etc...

What I liked:

• Nice getting started guide
• Fast static generation
• Easy GitHub deployment
• Markdown-friendly
• More flexibility than Bootstrap - eg more powerful links, react like components for things like nav bars, markdown support to easily turn a folder of posts into a cms like sortable post structure.
• Lots of free templates

What I didn’t:

• No native newsletter or analytics.
• Required a bit more wiring up (e.g., custom routing, metadata)
• Still felt like I’d be spending time tweaking instead of writing, especially when I added up my requirements (analytics - quite easy via Google, newsletters etc).

If I was building a custom blog or had time to spare, Astro would be a great choice - I could see it being fun, powerful and connecting something like PostHog, for more privacy centric analytics.

Step 4: Substack Again? Almost...

I briefly considered going back to Substack—its built-in email support was tempting—but the paywall-first model, low customisability, broad focus, didn’t feel right for what I wanted.

Step 5: Finding Hashnode

Eventually, I discovered Hashnode. It ticked nearly all my boxes:

• Custom domain support
• Free to use
• Newsletter integration
• Built-in analytics
• Developer-focused (Markdown, GitHub embeds, etc.)
• No hard sell on monetisation
• Customisable for the future, but easy to set up.
• Developer focused community
• Good for SEO

It felt like the right middle ground: more power and polish than Substack, less setup than Astro or Bootstrap... and importantly I wanted to allocate more time to building cool things... so I took the leap, got on Hashnode and published my first post (this one!).

Ultimately, I learned that clear requirements—even for personal projects—can save a lot of time building, researching, and second-guessing.

Lessons Learned

I approached this like a real project: defining requirements, prototyping, testing tools, iterating, refining my requirements and deciding what to use based on value vs. effort.

Here's my learning summary:

• Specs matter: even for personal projects, define your requirements early. It’ll save you time and indecision later. Specs are always a little emergent in that discovery phase, but it pays to define the key outcomes, upfront (as well as you can).
• Bootstrap is solid for simple landing pages, but not ideal for content-heavy blogs.
• Astro is brilliant, especially if you want to build something fully custom and fast.
• Substack is great if you're newsletter/ paywall first, want a broader audience **but not if you want control.
• Hashnode hits the sweet spot for developer blogs with minimal setup and good features.

What’s Next

I’ll be using this blog to share what I’m learning, document side projects, and reflect on my journey into software engineering, sharing my thoughts on the industry.

You can sign up for email updates here or follow my GitHub as I build stuff 🙂