From Idea to Maintainable UI: A Practical React/TS Sprint Workflow

Sem Gebresilassie — Sun, 15 Feb 2026 12:26:26 +0000

Most React projects don’t fail because React is hard. They fail because boundaries get fuzzy: API shapes aren’t explicit, components become “do-everything”, and small changes start causing unpredictable breakage.

When I join a project (or start one from scratch), I use a repeatable sprint workflow to turn an idea into a UI that’s actually maintainable: predictable contracts, clear structure, and small decisions that prevent a slow slide into chaos.

Below is the exact playbook I use in a 1–2 week sprint.

What “maintainable UI” means (in practice)

Maintainable doesn’t mean “perfect architecture”. It means:

You can add a feature without fear.
Onboarding doesn’t require tribal knowledge.
Bugs are isolated, not contagious.
The UI and the API agree on what’s true.

That last one (UI ↔ API alignment) is the biggest lever I’ve found for React + TypeScript.

The Sprint Workflow (1–2 weeks)

Step 1 — Clarify the outcome (½ day)

Before touching code, I write down:

Primary user flow (what are we trying to make easy?)
Success metric (what changes if we succeed?)
Non-goals (what we’re explicitly not doing in this sprint)

This prevents the sprint from turning into “a bunch of refactors”.

Step 2 — Lock the data contracts (day 1–2)

If the UI doesn’t have stable data contracts, TypeScript can’t save you.

I like a small “API layer” that:

centralizes requests,
encodes response types,
handles errors consistently.

Here’s a lightweight pattern that scales well:

// api/client.ts
export type ApiError = { message: string; status?: number };

export async function apiGet<T>(url: string): Promise<T> {
  const res = await fetch(url);

  if (!res.ok) {
    let message = `Request failed (${res.status})`;
    try {
      const body = await res.json();
      if (body?.message) message = body.message;
    } catch {
      // ignore parsing errors
    }
    throw { message, status: res.status } satisfies ApiError;
  }

  return (await res.json()) as T;
}

Then each feature defines the shapes it cares about:

// features/projects/types.ts
export type Project = {
  id: string;
  name: string;
  status: "draft" | "active" | "archived";
};

This isn’t complicated, but it gives you a stable “contract boundary”. Later, if you want runtime validation (Zod), it drops in cleanly.

Step 3 — Component contracts: make boundaries explicit (day 2–4)

The most common maintainability issue in React isn’t state management—it's “component sprawl”.

My rule:

components should receive data and callbacks,
not reach into the world to fetch things unless they’re a page-level component.

A clean interface usually looks like:

type ProjectCardProps = {
  project: Project;
  onOpen: (id: string) => void;
};

export function ProjectCard({ project, onOpen }: ProjectCardProps) {
  return (
    <button onClick={() => onOpen(project.id)}>
      {project.name}
    </button>
  );
}

Why this helps:

tests become trivial,
components become reusable,
debugging becomes “local”.

Step 4 — Choose a folder structure you’ll keep (day 3–5)

A maintainable UI needs a predictable map.

Two structures I’ve seen work consistently:

Option A — Feature-first

src/
  features/
    projects/
      components/
      hooks/
      types.ts
      api.ts
      index.ts
  shared/
    ui/
    lib/

Option B — Route-first (if the app is mostly pages)

src/
  routes/
    dashboard/
    settings/
  components/
  lib/

If in doubt, feature-first wins as the codebase grows.

Step 5 — State management: be boring on purpose (day 4–7)

Most apps don’t need a heavyweight state solution on day one.

My default stack:

server state: React Query / TanStack Query
local UI state: useState / useReducer
global UI state only if truly needed

The goal is fewer moving parts. Maintainability often improves when you remove abstractions, not add them.

Step 6 — Testing: a thin layer, high confidence (day 6–10)

I prefer a small, reliable testing approach:

Unit tests for pure logic (formatters, mappers, reducers)
Integration tests for a couple of key flows
Avoid shallow tests that only mirror implementation

You want tests that answer: “If we ship this change, did we break the product?”

Step 7 — Performance / UX: remove the obvious pain (day 7–12)

In a sprint, performance work should be pragmatic:

defer expensive animations until after first paint
reduce unnecessary rerenders
keep mobile layouts calm and readable

Small improvements here compound quickly because they reduce future friction.

The end result

After this workflow, you typically end up with:

clearer UI → API boundaries
smaller components with explicit contracts
a folder structure that doesn’t fight you
“boring” state that stays understandable
a couple of tests that matter
better mobile readability/performance

That’s what maintainable feels like: fast changes, fewer surprises.

If you want help applying this to your codebase

If you’re building a React/TypeScript product (or inheriting a messy one) and want to tighten it up in a focused sprint, you can find me here:

https://akukulu.com

(There’s a booking link on the page.)

The Twelve‑Factor App: Codebase + Dependencies (practical intro)

Sem Gebresilassie — Tue, 15 Sep 2020 11:37:30 +0000

If you build software that runs as a service (SaaS, APIs, web apps), the Twelve‑Factor App is still one of the clearest checklists for keeping things deployable and maintainable.

In my experience, two factors quietly cause a big share of real-world pain:

environments that drift (“staging is not prod”)
setups that aren’t repeatable (“it works on my machine”)

This post is a short, practical intro to two factors that prevent those problems:

Codebase — one repo, many deploys
Dependencies — declare everything explicitly

If you want the full set of factors, the official guide is here (worth reading end-to-end):
https://12factor.net/

1) Codebase — one repo, many deploys

In plain language: your app should have a single source of truth in version control (one codebase), and that same codebase should be deployed to multiple environments.

What this looks like in practice

One repository deployed to dev, staging, and production through the same pipeline.
You promote the same code forward (instead of rebuilding a different app per environment).

Common failure modes I see

A production hotfix is made directly in prod and never merged back.
“Staging” is pointed at a different repo/branch for convenience and silently diverges.
Teams copy/paste a shared “utils” folder into multiple repos and call it “shared code”.

The fix

Treat envs as deploys of the same codebase.
If multiple repos truly need shared functionality, extract a versioned dependency (package/library) instead of duplicating code.

2) Dependencies — declare everything explicitly

In plain language: the app should not rely on tools/libraries “just being installed” on a server or a developer’s laptop.

What this looks like in practice

Dependencies are declared in a manifest (package.json, requirements.txt, Gemfile, etc.).
CI uses a deterministic install (npm ci, locked versions, reproducible builds).
A new developer can clone the repo and get running without guessing what to install globally.

Common failure modes I see

Local uses one Node version; CI uses another; production uses a third.
No lockfile / loose ranges — builds change over time without code changes.
Global installs hide missing dependencies until deployment day.

The fix

Pin versions where it matters, commit the lockfile, and make CI match local setup.
Prefer repeatable install commands (e.g. npm ci in CI).

Read the rest (highly recommended)

The original Twelve‑Factor guide is short and extremely readable:

Codebase: https://12factor.net/codebase
Dependencies: https://12factor.net/dependencies
Full list: https://12factor.net/

If you want help applying this to a real codebase

If you’re building a React/TypeScript product (or inheriting a messy one) and want to tighten up your deployment + maintainability fundamentals in a focused sprint, you can find me here:

https://akukulu.com

Forem: Sem Gebresilassie

From Idea to Maintainable UI: A Practical React/TS Sprint Workflow

What “maintainable UI” means (in practice)

The Sprint Workflow (1–2 weeks)

Step 1 — Clarify the outcome (½ day)

Step 2 — Lock the data contracts (day 1–2)

Step 3 — Component contracts: make boundaries explicit (day 2–4)

Step 4 — Choose a folder structure you’ll keep (day 3–5)

Step 5 — State management: be boring on purpose (day 4–7)

Step 6 — Testing: a thin layer, high confidence (day 6–10)

Step 7 — Performance / UX: remove the obvious pain (day 7–12)

The end result

If you want help applying this to your codebase

The Twelve‑Factor App: Codebase + Dependencies (practical intro)

1) Codebase — one repo, many deploys

What this looks like in practice

Common failure modes I see

The fix

2) Dependencies — declare everything explicitly

What this looks like in practice

Common failure modes I see

The fix

Read the rest (highly recommended)

If you want help applying this to a real codebase