v1 Architecture

This starter kit is designed to create a monolithic web application. Why? Having a single app in a single repo makes the following easier:

• Dev setup - clone a single repo and you're ready to go;
• Routing - no need for CORS configuration or service discovery to connect the frontend and backend (see my blog post for more information on configuring single-page apps);
• CI/CD - no need for synchronising between multiple repos; and
• Code consistency - a single set of ESLint and Babel configuration, so you can use the same language features and code style throughout.

There are other ways to build apps with different trade-offs, e.g. microservice architectures have grown in popularity, but this is often a sensible starting point.

Development Mode

In development mode, started using npm run dev, Nodemon and the Webpack dev server are used to run the client and server separately, with requests to /api endpoints proxied to the backend.

Using a proxy like this gives us development-production parity; we don't to add need any special configuration for either client or server to run the app locally.

Development request lifecycle

The diagram below shows what happens when a page gets loaded in v1 Architecture#Development Mode:

sequenceDiagram
    actor Browser
    
    Browser -> +Webpack dev server: `GET :3000/...`
    note right of Webpack dev server: Responds to every client-side route ("page") with `index.html`
    Webpack dev server -> Webpack dev server: Served from `./client/src`
    Webpack dev server -> -Browser: `index.html`
    
    Browser -> +Webpack dev server: `GET :3000/{thing}.js`
    Webpack dev server -> Webpack dev server: Transpiled and served from `./client/src`
    Webpack dev server -> -Browser: `{thing}.js`
    
    Browser -> +Webpack dev server: `GET :3000/api/...`
    note right of Webpack dev server: `/api` routes are CRUD endpoints
    Webpack dev server -> +Express: *Proxy* - `GET :3100/api/...
    Express -> +Database: Read
    Database -> -Express: Data
    Express -> -Webpack dev server: `JSON`
    Webpack dev server -> -Browser: `JSON`

Loading

Production Mode

In production mode, started using npm run serve, all of the code is transpiled (using Babel) and the client code is bundled (using Webpack). Express serves both the API endpoints and the bundled client code.

This usage of build and start is to match the buildpack process used by e.g. Heroku, which basically carries out the following:

• npm install - install all of the dependencies
• npm run build - build the production code from the raw source
• npm prune --production - strip out the development dependencies
• npm start - run the production code

Production request lifecycle

The diagram below shows what happens when a page gets loaded in v1 Architecture#Production Mode:

sequenceDiagram
    actor Browser
    
    Browser -> +Server: `GET /...`
    Server -> Server: Loaded from `./dist/static/`
    note right of Server: Responds to every client-side route ("page") with `index.html`
    Server -> -Browser: `index.html`
    
    Browser -> +CDN: `GET /{thing}.js`
    note right of CDN: E.g. React is loaded from `unpkg.com`
    CDN -> -Browser: `{thing}.js`
    
    Browser -> +Server: `GET /{thing}.js`
    Server -> Server: Loaded from `./dist/static/`
    note right of Server: Bundled client code
    Server -> -Browser: `{thing}.js`
    
    Browser -> +Server: `GET /api/...`
    Server -> +Database: Read
    Database -> -Server: Data
    note right of Server: `/api` routes are CRUD endpoints
    Server -> -Browser: `JSON`

Loading