# zachgoll/microservices-architecture-example architecture

> Architecture diagram of the GitHub repository zachgoll/microservices-architecture-example, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zachgoll/microservices-architecture-example
- Repository: https://github.com/zachgoll/microservices-architecture-example

## Overview

##### What this project is (type + purpose)

This repository is a **Node.js microservices example application** composed of **three separately started processes**:

##### UI Static Server (`node app.js`) on http://localhost:8080
2. **Microservice #1: User Authentication** (`node user-authentication/server.js`) on **http://localhost:8081**
##### Microservice #2: Game (`node game/server.js`) on http://localhost:8082

Both microservices persist data in **MongoDB** using credentials provided via environment variables: `DB_USER`, `DB_PW`.

Purpose-wise, the UI combines two independently deployable services into a single user experience:
- Auth service: register/authenticate/get user
- Game service: submit score/get score history (wins/losses)

##### How the file tree maps to architecture (what to reflect

From the tree:

##### Root
- `app.js` → the **UI static server** (serves `/public` assets; likely Express or Node HTTP server)
- `public/` → front-end assets:
- `index.html` (entry page)
- `script.js` (calls microservices via HTTP)
- `style.css`
- `package.json` / `package-lock.json` → root dependencies for the UI server process

##### `user-authentication/`
- `server.js` → **Auth microservice HTTP API** listening on 8081
- `data.js` → auth data access layer / model definitions (MongoDB interactions)
- its own `package.json` / lock → indicates **independent service lifecycle** (separate dependencies, start commands, deployability)

##### `game/`
- `server.js` → **Game microservice HTTP API** listening on 8082
- `data.js` → game data access layer / model definitions (MongoDB interactions)
- its own `package.json` / lock → also independently deployable

**Key architectural implication to show:** this repo is “microservices” at the process boundary level: separate servers, separate dependency graphs, separate ports, communication over HTTP APIs, shared DB infra.

##### Clients / Edge
- **Browser** (end user)

##### UI tier
- **UI Static Server (Node)** `app.js` on `:8080`
- Serves `public/index.html`, `public/script.js`, `public/style.css`
- (Even if it’s “just static”, it’s a running server process and should be shown as such.)

##### Service tier (two microservices)
- **Auth Service (Node/Express)** `user-authentication/server.js` on `:8081`
- Endpoints (from README):
- `POST /register`
- `POST /authenticate`
- `GET /get-user/:useremail`
- **Game Service (Node/Express)** `game/server.js` on `:8082`
- Endpoints (from README):
- `POST /score`
- `GET /score/:email`

##### Data tier
- **MongoDB** (local in this tutorial; a single instance)
- As one DB server/cluster, but include **logical separation**:
- Collection for users (Auth service writes/reads)
- Collection for game results (Game service writes/reads)
- Credentials flow: both services use `DB_USER`/`DB_PW`

##### Static asset delivery
- **Browser → UI Static Server (:8080)**: `GET /` returns `index.html`, `GET /script.js`, etc.

##### Auth flows
- **Browser (script.js) → Auth Service (:8081)**:
- `POST /register` with `{email, password}`
- `POST /authenticate` with `{email, password}`
- optionally `GET /get-user/:useremail`

##### Game flows
- **Browser (script.js) → Game Service (:8082)**:
- `POST /score` with `{email, result(win/loss)}`
- `GET /score/:email`

##### Persistence
- **Auth Service → MongoDB**: create/read user records
- **Game Service → MongoDB**: upsert/read score records (wins/losses per email)

- Browser ⇄ services: HTTP + JSON payloads
- Services ⇄ MongoDB: Mongo wire protocol via Node Mongo/Mongoose driver (implementation detail, but worth labeling as “MongoDB driver”)

##### “Don’t overthink it”: split into as many components as possible (but keep it truthful)

Given this repo’s simplicity, the most valuable “extra detail” (without inventing architecture) is:

- Explicitly show that there are **three separate Node runtimes**.
- Explicitly show that **the browser JS calls microservices directly** (unless you confirm the UI server proxies; don’t assume proxying).
- Explicitly show **data ownership boundaries**:
- Auth service owns “User” data
- Game service owns “GameResult/Score” data
- Explicitly show **configuration boundary**:
- Environment variables (DB creds) injected into each microservice process

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Primary: Container Diagram
  %% =========================
  subgraph "Container Diagram (Runtime Processes + Data Store)"
    direction TB

    B(("Browser\n(End User)")):::client

    subgraph "UI Tier"
      direction TB
      UI["UI Static Server (Node)\n:8080"]:::ui
      PUB["Static Assets\n/public"]:::frontend
      IDX["index.html"]:::frontend
      JS["script.js\n(UI composition + API calls)"]:::frontend
      CSS["style.css"]:::frontend

      UI -->|"serves_static"| PUB
      PUB -->|"contains"| IDX
      PUB -->|"contains"| JS
      PUB -->|"contains"| CSS
    end

    subgraph "Service Tier (Microservices)"
      direction TB

      subgraph "Microservice #1: User Authentication"
        direction TB
        AUTH["Auth Service (Node/Express)\n:8081"]:::svc
        AUTH_ROUTES["HTTP API Routes\nPOST /register\nPOST /authenticate\nGET /get-user/:useremail"]:::route
        AUTH_DATA["Data Access Layer\n(data.js)"]:::data
        AUTH -->|"handles_requests"| AUTH_ROUTES
        AUTH_ROUTES -->|"uses"| AUTH_DATA
      end

      subgraph "Microservice #2: Game"
        direction TB
        GAME["Game Service (Node/Express)\n:8082"]:::svc
        GAME_ROUTES["HTTP API Routes\nPOST /score\nGET /score/:email"]:::route
        GAME_DATA["Data Access Layer\n(data.js)"]:::data
        GAME -->|"handles_requests"| GAME_ROUTES
        GAME_ROUTES -->|"uses"| GAME_DATA
      end
    end

    subgraph "Data Tier"
      direction TB
      MDB[(MongoDB\nsingle instance)]:::db
      USERS["Users Collection\n(logical)"]:::dbcomp
      SCORES["Scores Collection\n(logical)"]:::dbcomp
      MDB -->|"contains"| USERS
      MDB -->|"contains"| SCORES
    end

    B -->|"HTTP_GET_/ (HTML/CSS/JS)"| UI
    B -->|"HTTP/JSON\nPOST /register\nPOST /authenticate\nGET /get-user/:useremail"| AUTH
    B -->|"HTTP/JSON\nPOST /score\nGET /score/:email"| GAME

    AUTH_DATA -->|"MongoDB_driver\nread/write users"| USERS
    GAME_DATA -->|"MongoDB_driver\nread/write scores"| SCORES

    ENV["Env Vars\nDB_USER, DB_PW"]:::config
    ENV -->|"injected_into_process"| AUTH
    ENV -->|"injected_into_process"| GAME
  end

  %% ==================================
  %% Secondary: Auth Service Components
  %% ==================================
  subgraph "Auth Service Component Diagram"
    direction TB
    A_CLIENT(("Browser\n(public/script.js)")):::client
    A_HTTP["HTTP API\nuser-authentication/server.js\n:8081"]:::svc
    A_ROUTES["Routes/Controllers\n/register\n/authenticate\n/get-user/:useremail"]:::route
    A_DAL["Data Layer\nuser-authentication/data.js"]:::data
    A_DB[(MongoDB)]:::db
    A_USERS["Users Collection"]:::dbcomp

    A_CLIENT -->|"HTTP/JSON"| A_HTTP
    A_HTTP -->|"dispatches"| A_ROUTES
    A_ROUTES -->|"calls"| A_DAL
    A_DAL -->|"MongoDB_driver"| A_USERS
    A_DB -->|"contains"| A_USERS
  end

  %% ==================================
  %% Secondary: Game Service Components
  %% ==================================
  subgraph "Game Service Component Diagram"
    direction TB
    G_CLIENT(("Browser\n(public/script.js)")):::client
    G_HTTP["HTTP API\ngame/server.js\n:8082"]:::svc
    G_ROUTES["Routes/Controllers\n/score (POST)\n/score/:email (GET)"]:::route
    G_DAL["Data Layer\ngame/data.js"]:::data
    G_DB[(MongoDB)]:::db
    G_SCORES["Scores Collection"]:::dbcomp

    G_CLIENT -->|"HTTP/JSON"| G_HTTP
    G_HTTP -->|"dispatches"| G_ROUTES
    G_ROUTES -->|"calls"| G_DAL
    G_DAL -->|"MongoDB_driver"| G_SCORES
    G_DB -->|"contains"| G_SCORES
  end

  %% =========================
  %% Optional: Main Flow (High-Level)
  %% =========================
  subgraph "Main User Journey (High-Level)"
    direction TB
    S1["1) Load UI\nGET / (8080)"]:::step
    S2["2) Register\nPOST /register (8081)"]:::step
    S3["3) Authenticate\nPOST /authenticate (8081)"]:::step
    S4["4) Submit Result\nPOST /score (8082)"]:::step
    S5["5) Fetch History\nGET /score/:email (8082)"]:::step

    S1 --> S2 --> S3 --> S4 --> S5
  end

  %% Hidden nodes for dependency files (click targets without clutter)
  ROOT_PKG["package.json"]:::hidden
  ROOT_LOCK["package-lock.json"]:::hidden
  AUTH_PKG["user-authentication/package.json"]:::hidden
  AUTH_LOCK["user-authentication/package-lock.json"]:::hidden
  GAME_PKG["game/package.json"]:::hidden
  GAME_LOCK["game/package-lock.json"]:::hidden

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click UI "https://github.com/zachgoll/microservices-architecture-example/blob/master/app.js"
  click PUB "https://github.com/zachgoll/microservices-architecture-example/tree/master/public/"
  click IDX "https://github.com/zachgoll/microservices-architecture-example/blob/master/public/index.html"
  click JS "https://github.com/zachgoll/microservices-architecture-example/blob/master/public/script.js"
  click CSS "https://github.com/zachgoll/microservices-architecture-example/blob/master/public/style.css"

  click AUTH "https://github.com/zachgoll/microservices-architecture-example/blob/master/user-authentication/server.js"
  click AUTH_DATA "https://github.com/zachgoll/microservices-architecture-example/blob/master/user-authentication/data.js"
  click AUTH_ROUTES "https://github.com/zachgoll/microservices-architecture-example/blob/master/user-authentication/server.js"
  click A_HTTP "https://github.com/zachgoll/microservices-architecture-example/blob/master/user-authentication/server.js"
  click A_DAL "https://github.com/zachgoll/microservices-architecture-example/blob/master/user-authentication/data.js"

  click GAME "https://github.com/zachgoll/microservices-architecture-example/blob/master/game/server.js"
  click GAME_DATA "https://github.com/zachgoll/microservices-architecture-example/blob/master/game/data.js"
  click GAME_ROUTES "https://github.com/zachgoll/microservices-architecture-example/blob/master/game/server.js"
  click G_HTTP "https://github.com/zachgoll/microservices-architecture-example/blob/master/game/server.js"
  click G_DAL "https://github.com/zachgoll/microservices-architecture-example/blob/master/game/data.js"

  click ROOT_PKG "https://github.com/zachgoll/microservices-architecture-example/blob/master/package.json"
  click ROOT_LOCK "https://github.com/zachgoll/microservices-architecture-example/blob/master/package-lock.json"
  click AUTH_PKG "https://github.com/zachgoll/microservices-architecture-example/blob/master/user-authentication/package.json"
  click AUTH_LOCK "https://github.com/zachgoll/microservices-architecture-example/blob/master/user-authentication/package-lock.json"
  click GAME_PKG "https://github.com/zachgoll/microservices-architecture-example/blob/master/game/package.json"
  click GAME_LOCK "https://github.com/zachgoll/microservices-architecture-example/blob/master/game/package-lock.json"

  %% =========================
  %% Styles
  %% =========================
  classDef client fill:#e5e7eb,stroke:#111827,stroke-width:1px,color:#111827;
  classDef ui fill:#dbeafe,stroke:#1d4ed8,stroke-width:1.5px,color:#0f172a;
  classDef frontend fill:#eef2ff,stroke:#4338ca,stroke-width:1px,color:#0f172a;
  classDef svc fill:#bfdbfe,stroke:#1e40af,stroke-width:1.5px,color:#0f172a;
  classDef route fill:#c7d2fe,stroke:#3730a3,stroke-width:1px,color:#0f172a;
  classDef data fill:#e0f2fe,stroke:#0369a1,stroke-width:1px,color:#0f172a;
  classDef db fill:#dcfce7,stroke:#166534,stroke-width:1.5px,color:#052e16;
  classDef dbcomp fill:#bbf7d0,stroke:#15803d,stroke-width:1px,color:#052e16;
  classDef config fill:#fef3c7,stroke:#b45309,stroke-width:1.5px,color:#451a03;
  classDef step fill:#f3f4f6,stroke:#6b7280,stroke-width:1px,color:#111827;
  classDef hidden fill:#ffffff,stroke:#ffffff,color:#ffffff;
```
