Structuring an application

Each part of an app has one job

A JavaScript app often starts small, with a few event listeners. Then it grows. It loads data, checks what the user typed, saves to storage, and draws lists on the page. It gets more screens and tests. If all of that sits in one place, every change gets harder.

Application architecture is how you split an app into parts. Each part gets one job, and you decide which part does what.

This lesson uses ideas from earlier lessons. It links back instead of teaching them again: factories in Creational patterns, subscriptions in Observer & pub/sub, strategies and adapters in Structural & behavioral patterns, and keeping one copy of the data in State management.

There are three common ways to split the code that runs a page. The table compares them. Read each row as "this style splits the code like this, and you see it here".

You will use ideas from these lessons: functions, objects, classes, inheritance, OOP principles, modules, Web Components, and coding style. Architecture puts those ideas together for an app that keeps growing.

Here is a small todo app written as one big function, startTodoPage. Each line on its own is fine. The function does all of these jobs:

• loads the todos (line 7),
• clears the list and draws each todo,
• listens for the form's submit event (line 15),
• checks the title is at least 3 characters,
• saves the list to localStorage (line 24),
• and adds the new todo to the page.

No single line is wrong. The problem is that one function has many reasons to change. A new title rule, a new way to save, or a new look for the list all mean editing the same function.

1function fetchTodos(url) {2  console.log("fetch " + url);3  return [{ id: 1, title: "Read architecture", done: false }];4}5 6function startTodoPage() {7  const todos = fetchTodos("/todos.json");8  app.innerHTML = "";9  for (const todo of todos) {10    const item = document.createElement("li");11    item.textContent = todo.title;12    app.append(item);13  }14 15  form.addEventListener("submit", (event) => {16    event.preventDefault();17    const title = input.value.trim();18    if (title.length < 3) {19      error.textContent = "Use at least 3 characters";20      return;21    }22    const next = { id: Date.now(), title, done: false };23    todos.push(next);24    localStorage.setItem("todos", JSON.stringify(todos));25    const item = document.createElement("li");26    item.textContent = next.title;27    app.append(item);28  });29 30  console.log(app.textContent.trim());31}32 33startTodoPage();

Fix it one piece at a time. Each step moves one job into its own function:

1. Give the title rule a name: normalizeTitle (line 1).
2. Put saving and loading behind load and save, inside createTodoStore (line 7).
3. Make drawing a function, renderTodoList, that gets the todos and the place on the page to draw them (line 18).

The code at the bottom still connects the parts. But now you can test each function on its own.

1function normalizeTitle(raw) {2  const title = raw.trim();3  if (title.length < 3) throw new Error("Use at least 3 characters");4  return title;5}6 7function createTodoStore(storage) {8  return {9    load() {10      return JSON.parse(storage.getItem("todos") ?? "[]");11    },12    save(todos) {13      storage.setItem("todos", JSON.stringify(todos));14    },15  };16}17 18function renderTodoList(root, todos) {19  const list = document.createElement("ul");20  for (const todo of todos) {21    const item = document.createElement("li");22    item.textContent = todo.title;23    list.append(item);24  }25  root.replaceChildren(list);26}27 28const fakeStorage = {29  value: "[]",30  getItem() { return this.value; },31  setItem(_key, value) { this.value = value; },32};33const todos = [{ id: 1, title: normalizeTitle("  Write tests  "), done: false }];34const store = createTodoStore(fakeStorage);35store.save(todos);36renderTodoList(app, todos);37console.log(JSON.parse(fakeStorage.value)[0].title);38console.log(app.textContent.trim());

Three words help here:

• State is the app's current data, like the list of todos.
• The view turns that data into something on the page.
• A data service loads or saves the data.

The view gets the state it should show. It should not decide where that state came from.

const todos = [{ title: "Write tests" }];
function renderTodos(items) {
  return items.map((todo) => todo.title).join(", ");
}
console.log(todos.length);
console.log(renderTodos(todos));

Line 1 holds the todo data. Lines 2 to 4 turn any list they get into text, without changing the list. Line 5 prints 1, the number of todos. Line 6 prints Write tests, the text the view made.

1function normalizeTitle(raw) {Run2  const title = raw.trim();3  if (title.length < 3) throw new Error("Use at least 3 characters");4  return title;5}6 7function addTodo({ todos, title, storage, render }) {8  const cleanTitle = normalizeTitle(title);9  const nextTodos = [...todos, { id: todos.length + 1, title: cleanTitle }];10  storage.save(nextTodos);11  render(nextTodos);12  return nextTodos;13}14 15const storage = { save: (todos) => console.log("saved:" + todos.length) };16const render = (todos) => console.log("rendered:" + todos.length);17const state = addTodo({ todos: [], title: "  Plan modules  ", storage, render });18console.log(state.length);

In the step-through, line 8 checks the title. Line 9 makes the new list. Lines 10 and 11 call the two helpers that were passed in: one saves, one draws. It is the same feature as before, but now you can see everything addTodo needs.

MVC stands for Model, View, Controller. It splits the code into three parts:

• The model holds the data and its rules (lines 1 to 11).
• The view draws the page and tells others what the user did (lines 13 to 34).
• The controller handles input and tells the model and the view what to do (lines 36 to 41).

The controller also has its own add method. So a form submit and a direct call like controller.add("Review architecture") (line 47) both go through the same model rule.

1function createTodoModel(initial = []) {2  const todos = [...initial];3  return {4    all() { return [...todos]; },5    add(title) {6      const clean = title.trim();7      if (clean.length < 3) throw new Error("Use at least 3 characters");8      todos.push({ id: todos.length + 1, title: clean, done: false });9    },10  };11}12 13function createTodoView(root) {14  root.innerHTML = '<form><input aria-label="Todo"><button>Add</button></form><ul></ul>';15  const form = root.querySelector("form");16  const input = root.querySelector("input");17  const list = root.querySelector("ul");18  return {19    onAdd(handler) {20      form.addEventListener("submit", (event) => {21        event.preventDefault();22        handler(input.value);23        input.value = "";24      });25    },26    render(todos) {27      list.replaceChildren(...todos.map((todo) => {28        const item = document.createElement("li");29        item.textContent = todo.title;30        return item;31      }));32    },33  };34}35 36function createTodoController(model, view) {37  const refresh = () => view.render(model.all());38  view.onAdd((title) => { model.add(title); refresh(); });39  refresh();40  return { add(title) { model.add(title); refresh(); } };41}42 43const controller = createTodoController(44  createTodoModel(),45  createTodoView(document.querySelector("#mvc-demo")),46);47controller.add("Review architecture");48console.log(document.querySelector("#mvc-demo li").textContent);

MVVM stands for Model, View, View-model. The view-model sits between the data and the page. It holds two things for the view:

• data the view can watch, so it knows when to draw again (an observable, line 1),
• and commands, which are methods the view calls, like addTodo.

The view connects its events to those commands (lines 39 and 40). It also subscribes to the data (line 44): when the data changes, the list is drawn again. Frameworks that redraw the page when data changes feel like this.

1function observableState(initial) {2  let state = initial;3  const listeners = new Set();4  return {5    get() { return state; },6    set(updater) {7      state = updater(state);8      listeners.forEach((listener) => listener(state));9    },10    subscribe(listener) {11      listeners.add(listener);12      listener(state);13      return () => listeners.delete(listener);14    },15  };16}17 18function createTodoViewModel(storage) {19  const todos = observableState(storage.load());20  return {21    todos,22    newTitle: "",23    setTitle(value) { this.newTitle = value; },24    addTodo() {25      const title = this.newTitle.trim();26      if (title.length < 3) return;27      todos.set((items) => [...items, { id: items.length + 1, title, done: false }]);28      storage.save(todos.get());29      this.newTitle = "";30    },31  };32}33 34function bindTodoView(root, viewModel) {35  root.innerHTML = '<input aria-label="Todo"><button>Add</button><ul></ul>';36  const input = root.querySelector("input");37  const button = root.querySelector("button");38  const list = root.querySelector("ul");39  input.addEventListener("input", () => viewModel.setTitle(input.value));40  button.addEventListener("click", () => {41    viewModel.addTodo();42    input.value = viewModel.newTitle;43  });44  viewModel.todos.subscribe((todos) => {45    list.replaceChildren(...todos.map((todo) => {46      const item = document.createElement("li");47      item.textContent = todo.title;48      return item;49    }));50  });51}52 53const memoryStorage = { load: () => [], save: (todos) => console.log("saved:" + todos.length) };54const vm = createTodoViewModel(memoryStorage);55bindTodoView(document.querySelector("#mvvm-demo"), vm);56vm.setTitle("Review architecture");57vm.addTodo();58console.log(document.querySelector("#mvvm-demo li").textContent);

Frameworks mix these ideas:

• React is not MVC, but its components still keep drawing apart from the data and the event handlers.
• Vue often feels like MVVM, because its templates watch data and redraw when it changes.
• Angular uses components, and passes helpers in for you (dependency injection, later in this lesson).

The names are useful when they help you see where one part ends and the next begins.

A component is one small, self-contained piece of the page, like one todo item. In plain JavaScript it can be a function that returns a page element. React, Vue, Svelte, and Web Components add more tools, but the rule is the same: data goes in as props (an object with the data to show), and events come out.

1function TodoItem({ todo }) {Run2  const item = document.createElement("li");3  item.textContent = (todo.done ? "Done: " : "Todo: ") + todo.title;4  return item;5}6 7function TodoList({ todos }) {8  const list = document.createElement("ul");9  for (const todo of todos) list.append(TodoItem({ todo }));10  return list;11}12 13function render(component, props, root) {14  root.replaceChildren(component(props));15}16 17let todos = [{ id: 1, title: "Draft lesson", done: false }];18render(TodoList, { todos }, document.querySelector("#component-demo"));19todos = todos.map((todo) => todo.id === 1 ? { ...todo, done: true } : todo);20render(TodoList, { todos }, document.querySelector("#component-demo"));21console.log(document.querySelector("#component-demo").textContent.trim());

The code below is the same tiny example, without the step player:

• TodoItem doesn't know where its data came from. It just shows it.
• TodoList is built from TodoItems.
• The top-level code changes todos and calls render again.

In a real app, the framework updates the page for you, but the idea is the same.

1function TodoItem({ todo }) {2  const item = document.createElement("li");3  item.textContent = (todo.done ? "Done: " : "Todo: ") + todo.title;4  return item;5}6 7function TodoList({ todos }) {8  const list = document.createElement("ul");9  for (const todo of todos) list.append(TodoItem({ todo }));10  return list;11}12 13function render(component, props, root) {14  root.replaceChildren(component(props));15}16 17let todos = [{ id: 1, title: "Draft lesson", done: false }];18render(TodoList, { todos }, document.querySelector("#component-demo"));19todos = todos.map((todo) => todo.id === 1 ? { ...todo, done: true } : todo);20render(TodoList, { todos }, document.querySelector("#component-demo"));21console.log(document.querySelector("#component-demo").textContent.trim());

A dependency is something your code needs to do its job. It might be storage, a client that talks to the server, a function that makes IDs, a clock, or a logger.

Dependency injection means the caller passes that helper in, usually as an argument. Your code doesn't reach for a fixed global like localStorage. It only expects a small contract: a few methods with known names, like get and set.

function createTodoService(getTodos) {
  return { list: () => getTodos("/todos") };
}
const getTodos = (path) => {
  console.log("GET " + path);
  return [{ title: "Write tests" }];
};
const todoService = createTodoService(getTodos);
console.log(todoService.list()[0].title);

Line 1 makes a service around a data function that is passed in. Line 2 keeps the address /todos inside the service, so callers ask for todos and never build the request. The data function prints GET /todos. Then line 9 prints Write tests.

function renderTodoList(root, todos) {
  const list = document.createElement("ul");
  for (const todo of todos) {
    const item = document.createElement("li");
    item.textContent = todo.title;
    list.append(item);
  }
  root.replaceChildren(list);
}
function createTodoPage(service, root) {
  renderTodoList(root, service.list());
}
const root = document.createElement("div");
createTodoPage(todoService, root);
console.log(root.textContent);

createTodoPage (line 10) gets the service, loads the todos, and passes them to renderTodoList (line 11). The view builds the page elements but knows nothing about the address or the server. It uses textContent (line 5), so a todo title is always shown as plain text and never turned into HTML. Line 15 prints Write tests.

function normalizeTitle(raw) {
  return raw.trim();
}
function saveTodo(storage, title) {
  storage.set("todo", title);
}
const storage = { value: "", set(key, value) { this.value = key + ":" + value; } };
const title = normalizeTitle(" Write tests ");
saveTodo(storage, title);
console.log(title);
console.log(storage.value);

normalizeTitle is pure: it only turns one value into another and touches nothing else. So you can test it without a browser. saveTodo does the saving through a storage object that is passed in. The last two lines print Write tests and todo:Write tests.

1function memoryStorage(seed = {}) {2  const data = { ...seed };3  return {4    get(key) { return data[key] ?? "[]"; },5    set(key, value) { data[key] = value; },6  };7}8 9function createTodoRepository({ storage, key = "todos", nextId = () => "todo-1" }) {10  return {11    all() { return JSON.parse(storage.get(key)); },12    add(title) {13      const todos = [...this.all(), { id: nextId(), title }];14      storage.set(key, JSON.stringify(todos));15      return todos.at(-1);16    },17  };18}19 20const repo = createTodoRepository({ storage: memoryStorage() });21console.log(repo.add("Inject storage").title);22console.log(repo.all().length);

This is also why tests use mocks and fakes. A fake storage can record each set call, start with a list of todos, or pretend to fail. It never touches real browser storage.

In the real app, one place at the start connects everything: the real storage, the server client, the clock, and the page. This place is called the composition root.

1function createContainer(registry) {2  const cache = new Map();3  const container = {4    get(name) {5      if (!cache.has(name)) cache.set(name, registry[name](container));6      return cache.get(name);7    },8  };9  return container;10}11 12const container = createContainer({13  storage: () => {14    const data = { todos: "[]" };15    return { get: (key) => data[key], set: (key, value) => { data[key] = value; } };16  },17  todos: ({ get }) => ({18    all: () => JSON.parse(get("storage").get("todos")),19    add(title) {20      const todos = [...this.all(), { id: "container-1", title }];21      get("storage").set("todos", JSON.stringify(todos));22      return todos.at(-1);23    },24  }),25});26console.log(container.get("todos").add("Container aside").title);27console.log(container.get("todos") === container.get("todos"));

A DI container is an object that creates your helpers for you and hands them out by name. Line 1 makes one. Line 12 tells it how to build storage and todos. It creates each helper once and reuses it, so the last line prints true.

Many JavaScript apps don't need a container. Plain arguments and one composition root are easier to follow. Reach for a container only when you write the same connecting code again and again.

Good app structure starts with clean code: clear names, small functions, and code that shows what it changes.

SOLID is a set of five design rules. Each letter is one rule. They are often taught with Java classes, but they work in JavaScript too. Here they mean small focused functions, small objects, and behavior you can swap.

The table lists the rules that keep design practical. Read each row as "the rule, what it means in JavaScript, and an example".

S, single responsibility: one reason to change

The first function, addTodoMixed (line 1), checks the title, saves it, and draws it. The functions after it give each job its own name: normalizeTodoTitle (line 8), then saveTodo and renderTodo (lines 13 and 14). The example is small, but the same habit works for whole files.

1function addTodoMixed(raw, storage, list) {2  const title = raw.trim();3  if (title.length < 3) throw new Error("Use at least 3 characters");4  storage.saved = title;5  list.push(title);6}7 8function normalizeTodoTitle(raw) {9  const title = raw.trim();10  if (title.length < 3) throw new Error("Use at least 3 characters");11  return title;12}13function saveTodo(storage, todo) { storage.saved = todo.title; }14function renderTodo(list, todo) { list.push(todo.title); }15 16const storage = {};17const list = [];18const todo = { title: normalizeTodoTitle("  Learn SOLID  ") };19saveTodo(storage, todo);20renderTodo(list, todo);21console.log(storage.saved);22console.log(list.join(", "));

O, open/closed: add new behavior without editing old code

A strategy is a small function you pass in to choose the behavior. Here each discount is one strategy (line 1). To add a new discount, you add a function. You don't edit totalAfterDiscount (line 7). The code is open to new discounts but closed to edits. You saw strategies in the structural and behavioral patterns lesson.

1const discountStrategies = {2  none: (total) => total,3  tenPercent: (total) => total * 0.9,4  fiveOff: (total) => Math.max(0, total - 5),5};6 7function totalAfterDiscount(total, strategy) {8  return strategy(total).toFixed(2);9}10 11console.log(totalAfterDiscount(10, discountStrategies.tenPercent));12console.log(totalAfterDiscount(10, discountStrategies.fiveOff));

L, Liskov substitution: a stand-in must keep the promise

Code that gets a rectangle expects setSize(4, 5) to make the width 4 and the height 5. Square (line 6) extends Rectangle but ignores the height. So areaAfterResize (line 10) gets 20 for a rectangle (line 15) but 16 for a square. The square breaks the rectangle's promise.

A safer choice: give shapes a smaller shared promise, like "every shape has area()". The square function on line 18 does that, and prints 25.

1class Rectangle {2  setSize(width, height) { this.width = width; this.height = height; }3  area() { return this.width * this.height; }4}5 6class Square extends Rectangle {7  setSize(width) { this.width = width; this.height = width; }8}9 10function areaAfterResize(shape) {11  shape.setSize(4, 5);12  return shape.area();13}14 15console.log(areaAfterResize(new Rectangle()));16console.log(areaAfterResize(new Square()));17 18const square = (size) => ({ area: () => size * size });19console.log(square(5).area());

I and D: ask for small helpers, not big ones

These two rules are interface segregation and dependency inversion. JavaScript has no formal interfaces, but the rules still help:

• Pass in the smallest object or function the code needs.
• Depend on any storage with get and set, not on direct localStorage calls deep inside a file.

sendReceipt (line 1) only needs a mailer with send. loadPreference (line 5) only needs something with get. Line 9 makes a small fake mailer to try it out.

1function sendReceipt({ mailer }, address) {2  mailer.send(address, "Receipt");3}4 5function loadPreference(settingsStore) {6  return settingsStore.get("theme") ?? "system";7}8 9const fakeMailer = { sent: [], send(to, text) { this.sent.push(to + ":" + text); } };10sendReceipt({ mailer: fakeMailer }, "ada@example.com");11console.log(fakeMailer.sent[0]);12console.log(loadPreference({ get: () => "dark" }));

KISS, YAGNI, and DRY: don't add layers you don't need

Extra layers hurt when nothing changes yet. These three rules keep code simple:

• KISS (keep it simple): use the plain, direct code.
• YAGNI (you aren't gonna need it): wait until a second real use shows up before you add a layer.
• DRY (don't repeat yourself): keep each rule in one place. Lines that only look alike can stay.

Line 1 wraps one small text change in a big, vague name. Line 5 does the same work as a plain function. Both print SHIP IT, but the plain one is easier to read.

1function createFactoryBuilderStrategyAdapter(value) {2  return { execute: () => value.trim().toUpperCase() };3}4 5const directTitle = (value) => value.trim().toUpperCase();6console.log(directTitle("  ship it  "));7console.log(createFactoryBuilderStrategyAdapter("  ship it  ").execute());

Folders give a hint about how an app is split, but they are not the split itself. There are two common ways to sort files:

• By feature: all the code for one screen or topic sits together.
• By type: all components in one folder, all models in another. This is easy for a small app.

Most bigger apps end up with a mix of both. The table compares the three choices. Read each row as "the choice, example paths, and what you gain or lose".

src/
  features/
    todos/
      TodoList.js
      todoModel.js
      todoRepository.js
    settings/
      SettingsPanel.js
  shared/
    dom.js
    storage.js

src/
  components/
    TodoList.js
    SettingsPanel.js
  models/
    todoModel.js
  services/
    todoRepository.js

The dependency direction is which file imports which. It is not the way todo data moves while the app runs. Some rules for it:

• Page code can read the data rules.
• Data rules should not import the page, browser storage, or a server client.
• One top file, like a page or the composition root, can import all the parts and connect them.
• In a bigger app, the rules can ask for a small storage contract, and a browser file can provide it.

If two files import each other, move the connecting code up into a third file that imports both.

In the code below, the model imports the view (line 2), and the view imports the model (line 10). That is a circular dependency: two files that import each other.

1// todoModel.js2import { renderTodo } from "./todoView.js"; // model now knows the view3export function addTodo(title) {4  const todo = { title };5  renderTodo(todo);6  return todo;7}8 9// todoView.js10import { addTodo } from "./todoModel.js"; // view now knows the model11button.addEventListener("click", () => addTodo(input.value));

Common misconceptions

• “Architecture is just folder names.” Folders help. But the real design is which part does each job, and which file imports which.
• “MVC means old code.” Modern frameworks still keep data rules, drawing, and input handling apart.
• “MVVM means hidden magic everywhere.” A view-model can have plain commands and data you watch, with no hidden rules.
• “With components, you don't need architecture.” Components still need an owner for the data, a place for side effects, clear files, and tests.
• “Dependency injection needs a container.” Passing helpers in as arguments is already dependency injection.
• “SOLID means writing more classes.” In JavaScript, functions and plain objects often follow the rules better.

The table turns four common claims into a better question to ask, and a step to take.

Key takeaways

• Architecture means giving each part of the app one job. Folder names alone are not architecture.
• MVC splits code into a model, a view, and a controller. MVVM adds a view-model with data to watch and commands to call.
• Components work best when props go in, events come out, big parts are built from small parts, and data flows one way.
• Dependency injection is just passing helpers in as arguments. It makes code easy to test and easy to swap.
• SOLID in JavaScript means small contracts, stand-ins that keep their promises, strategies, and asking for helpers instead of grabbing globals.
• KISS, YAGNI, and DRY stop you from building layers for problems you don't have.

One-line summary: give each part of the app one clear job, pass its helpers in, and use the simplest pattern that keeps each change in one place.

Up next: Designing good APIs. That lesson is about the functions and files each part shows to the rest of the app, and how to make them easy to use correctly.