ComputeSphereLearn
Console
Learning paths / Application foundations / Architecture 101

Web, API, database, worker: a reference architecture

Reading · 6 min · Module 8, lesson 2 of 416 min left in this module

Module 8 · Architecture 101Lesson 2 of 4

Goal: Draw the four parts of a typical web app, what each one does, and which parts connect to which.

3:22 · captions and chapters · narrated with an AI-generated voice
Transcript

Narration uses an AI-generated voice.

[00:00] Where we're going

By the end of this video, you'll be able to draw the four parts of a typical web app. What each one does, and which parts connect to which.

[00:09] The four parts

Most web apps grow into four parts. First, the web. It's what the visitor's browser loads. It shows things and collects input, then asks the API for everything else. Second, the API. It holds the rules of the product. Who may do what, what an order looks like, and which status code to return.

Third, the database. It keeps the records, like users, orders and jobs. It keeps them across every deploy, so nothing else needs to keep data on its own disk. And fourth, the worker. It does work that shouldn't hold up a request. Sending the confirmation email, making the PDF, or calling a slow partner API. The worker has no address, and nothing calls it.

[00:58] Who talks to whom

Now, which parts connect? The browser talks to the web, over HTTPS. The web talks to the API, and only to the API. The API reads and writes the database. And so does the worker. Only those two talk to the database. The web never does, so the rules stay in one place.

[01:19] Follow one request

Let's follow one request. A customer places an order. The web sends it to the API. The API saves the order in the database. Then it adds a row to a jobs table: send confirmation for order forty-two. And it answers straight away, with two-oh-one, Created. Nobody waits for the email.

[01:41] Follow one job

Now the job. The API and the worker never call each other. They meet in the database. Every few seconds, the worker checks the jobs table. It finds the new row, sends the email, and marks the job done. What if the worker is down for a minute? The jobs wait in the table, and nothing is lost. As the app grows, the table can be swapped for a dedicated queue service.

[02:08] On ComputeSphere

On ComputeSphere, the web is a web service. A single-page app's built files can be a static site instead. The API is a web service too, with its own URL. The worker is a background worker, with no URL. And the database? ComputeSphere doesn't run databases, so it's hosted by a database provider. The API and the worker get its connection string as a secret.

All three services sit in one environment. So staging gets its own copies of all three, pointed at a staging database.

[02:43] Recap

So, a quick recap. The web shows things. The API holds the rules. The database keeps the data. The worker does the slow jobs. And only the API and the worker talk to the database.

[02:58] Check yourself

Here's a question to check yourself. The worker crashes and restarts. What happens to the emails queued while it was down? They're sent once the worker is back. The jobs are rows in the database, not in the worker's memory. Next up: what scales, and what doesn't. I'll see you there.

Key idea

Most web apps grow into four parts: a web frontend people visit, an API that holds the rules, a database that keeps the data, and a worker that does slow jobs in the background. Only the API and the worker talk to the database.

  browser
     │  HTTPS
     ▼
  ┌───────┐  HTTPS   ┌───────┐   TLS    ┌──────────┐   TLS    ┌────────┐
  │  web  │ ───────▶ │  API  │ ───────▶ │ database │ ◀─────── │ worker │
  └───────┘          └───────┘          └──────────┘          └────────┘
  web service        web service        hosted elsewhere      background worker

The four parts

Web. What the visitor's browser loads: a server-rendered app, or the built files of a single-page app. It shows things and collects input, then asks the API for everything else.

In a small server-rendered app, the web part and the API are often one service that reads the database itself, as in lesson 2.1.2. This lesson shows them apart, the shape most apps grow into.

API. The rules of the product: who may do what, what an order looks like, which status code to return. It's the only part the web talks to, and the one that reads and writes the database for requests.

Database. The records: users, orders, jobs. It keeps them across every deploy, so nothing else needs to keep data on its own disk.

Worker. Work that shouldn't hold up a request: sending the confirmation email, making the PDF, calling a slow partner API. It has no address, and nothing calls it.

How a job reaches the worker

The API and the worker never call each other. They meet in the database:

  1. A customer places an order. The API saves it and adds a row to a jobs table: "send confirmation for order 42".
  2. The API answers straight away, with 201 Created.
  3. The worker checks the jobs table every few seconds, finds the new row, sends the email and marks the job done.

If the worker is down for a minute, jobs wait in the table and nothing is lost. As the app grows, the table can be swapped for a dedicated queue service.

On ComputeSphere

  • Web: a web service. A single-page app's built files can be a static site instead.
  • API: a web service, with its own URL.
  • Worker: a background worker, with no URL.
  • Database: hosted by a database provider, because ComputeSphere doesn't run databases. The API and the worker get its connection string as a secret.

All three services sit in one environment, so staging gets its own copies of all three, pointed at a staging database.

Keeping the web-to-API call off the internet

By default the web service calls the API at the API's public URL. An environment can have Private network turned on, so its services reach each other by a private address instead. It's chosen when the environment is created; lesson 5.5.3 shows how.

Check yourself

In this architecture, which parts connect to the database?
The worker crashes and restarts. What happens to the emails queued while it was down?

In the docs