# hapijs/basic architecture

> Architecture diagram of the GitHub repository hapijs/basic, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hapijs/basic
- Repository: https://github.com/hapijs/basic

## Overview

1. **What this repository is**
   - `@hapi/basic` is a **small authentication plugin library**, not an application.
   - Its role is to add **HTTP Basic Authentication** support to the hapi ecosystem, while remaining usable in other Node.js server setups.

2. **Core architectural shape**
   - The repo is essentially a **single package with one implementation surface**:
     - `lib/index.js` — runtime implementation
     - `lib/index.d.ts` — TypeScript type definitions
   - The rest of the repository supports documentation, tests, and CI.

3. **Primary subsystem: authentication plugin**
   - The main subsystem is the **Basic auth scheme/plugin**.
   - It sits on the request path and handles authentication for inbound HTTP requests carrying Basic credentials.
   - Conceptually, the flow is: **request → plugin parses Basic auth header → credentials are validated → request is accepted or rejected**.

4. **Integration boundary**
   - The most important boundary is between:
     - the **server/framework layer** (especially hapi), and
     - the **authentication plugin**
   - The plugin is designed to be registered into a host application rather than run standalone, so the application controls how authentication is wired into routes/policies.

5. **Credential validation responsibility**
   - The repo is an auth mechanism, not a user store.
   - In architecture terms, this means the plugin handles **protocol-level auth processing** while the host app supplies the **business-specific identity/credential check** and decides what authenticated principal means.

6. **Public API and documentation**
   - `API.md` and the README point to the package’s **contract surface** and usage expectations.
   - The docs are part of the architecture because this repository is a reusable library: its behavior is defined more by its exported API than by internal service composition.

7. **Testing subsystem**
   - `test/index.js`, `test/index.ts`, and `test/esm.js` indicate the package is validated across:
     - **CommonJS/Node usage**
     - **TypeScript consumption**
     - **ES module consumption**
   - This is important architecturally because compatibility across module systems is part of the deliverable.

8. **CI and release validation**
   - `.github/workflows/ci-plugin.yml` provides automated verification of the package.
   - The CI boundary is focused on **library correctness and compatibility**, not deployment of a runtime service.

9. **Dependencies and runtime context**
   - The repository is in the **hapi ecosystem** and is meant to integrate with hapi’s plugin/authentication model.
   - Runtime footprint is minimal: this is a **Node.js library package**, not an infrastructure-backed service.

10. **Data flow summary**
   - External client sends request with Basic auth credentials.
   - Host server invokes the plugin during authentication.
   - Plugin interprets the credentials and coordinates validation.
   - The server either establishes an authenticated request context or returns an authentication failure.

11. **What is notably absent**
   - There are no persistence layers, queues, databases, or background jobs in this repo.
   - That absence is architecturally significant: the package is a **stateless protocol/authentication component**.

12. **How to diagram it**
   - Draw it as a **library/plugin block** between the HTTP server and the application’s auth validation logic.
   - Separate out:
     - **runtime library**
     - **public API/docs**
     - **multi-format tests**
     - **CI validation**
   - Do not model any data store or service mesh; the package’s architecture is intentionally lightweight.

Main entry points: [`lib/index.js`](https://github.com/hapijs/basic/blob/master/lib/index.js) (Basic plugin), [`.github/workflows/ci-plugin.yml`](https://github.com/hapijs/basic/blob/master/.github/workflows/ci-plugin.yml) (CI workflow), [`API.md`](https://github.com/hapijs/basic/blob/master/API.md) (API contract), [`test/index.js`](https://github.com/hapijs/basic/blob/master/test/index.js) (CJS test)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Integration"]
  node_external_client(("Client request<br/>external"))
  node_host_server["Host server"]
  node_auth_integration{{"Auth boundary<br/>integration"}}
  node_app_validator["App validator<br/>host logic"]
end

subgraph group_runtime["Runtime"]
  node_basic_plugin["Basic plugin<br/>auth scheme<br/>[index.js]"]
  node_header_parser["Header parse<br/>protocol parser<br/>[index.js]"]
  node_credential_gate{{"Validate creds<br/>validation gate<br/>[index.js]"}}
  node_auth_result(("Auth result<br/>request outcome<br/>[index.js]"))
  node_package_manifest["Package manifest<br/>package metadata<br/>[package.json]"]
end

subgraph group_docs["Docs"]
  node_api_contract["API contract<br/>reference<br/>[API.md]"]
  node_readme_usage["Usage guide<br/>reference<br/>[README.md]"]
end

subgraph group_tests["Tests"]
  node_cjs_test["CJS test<br/>[index.js]"]
  node_ts_test["TS test<br/>[index.ts]"]
  node_esm_test["ESM test<br/>[esm.js]"]
end

subgraph group_ci["CI"]
  node_ci_workflow["CI workflow<br/>pipeline<br/>[ci-plugin.yml]"]
end

node_external_client -->|"sends request"| node_host_server
node_host_server -->|"invokes auth"| node_auth_integration
node_auth_integration -->|"registers plugin"| node_basic_plugin
node_basic_plugin -->|"parses header"| node_header_parser
node_header_parser -->|"passes credentials"| node_credential_gate
node_credential_gate -->|"delegates check"| node_app_validator
node_app_validator -->|"returns decision"| node_auth_result
node_auth_result -->|"updates request"| node_host_server
node_api_contract -->|"describes behavior"| node_basic_plugin
node_readme_usage -->|"shows usage"| node_basic_plugin
node_package_manifest -->|"exposes entrypoint"| node_basic_plugin
node_cjs_test -->|"verifies"| node_basic_plugin
node_ts_test -->|"verifies types"| node_api_contract
node_esm_test -->|"verifies"| node_basic_plugin
node_ci_workflow -->|"runs"| node_cjs_test
node_ci_workflow -->|"runs"| node_ts_test
node_ci_workflow -->|"runs"| node_esm_test

click node_basic_plugin "https://github.com/hapijs/basic/blob/master/lib/index.js"
click node_header_parser "https://github.com/hapijs/basic/blob/master/lib/index.js"
click node_credential_gate "https://github.com/hapijs/basic/blob/master/lib/index.js"
click node_auth_result "https://github.com/hapijs/basic/blob/master/lib/index.js"
click node_api_contract "https://github.com/hapijs/basic/blob/master/API.md"
click node_readme_usage "https://github.com/hapijs/basic/blob/master/README.md"
click node_cjs_test "https://github.com/hapijs/basic/blob/master/test/index.js"
click node_ts_test "https://github.com/hapijs/basic/blob/master/test/index.ts"
click node_esm_test "https://github.com/hapijs/basic/blob/master/test/esm.js"
click node_ci_workflow "https://github.com/hapijs/basic/blob/master/.github/workflows/ci-plugin.yml"
click node_package_manifest "https://github.com/hapijs/basic/blob/master/package.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_external_client,node_host_server,node_auth_integration,node_app_validator toneBlue
class node_basic_plugin,node_header_parser,node_credential_gate,node_auth_result,node_package_manifest toneAmber
class node_api_contract,node_readme_usage toneMint
class node_cjs_test,node_ts_test,node_esm_test toneRose
class node_ci_workflow toneIndigo
```

## Components

### Integration

Host application and external request flow around the plugin

- **Client request**: external · HTTP client sending Basic credentials
- **Host server**: app · Application or hapi server that registers and invokes the plugin
- **Auth boundary**: integration · Where the host wires the plugin into its authentication flow
- **App validator**: host logic · Business-specific identity and credential verification owned by the application

### Runtime

Library implementation of the Basic auth scheme

- [Basic plugin](https://github.com/hapijs/basic/blob/master/lib/index.js): auth scheme · Primary runtime entry that implements HTTP Basic Authentication · `lib/index.js`
- [Header parse](https://github.com/hapijs/basic/blob/master/lib/index.js): protocol parser · Interprets the Authorization header and extracts Basic credentials · `lib/index.js`
- [Validate creds](https://github.com/hapijs/basic/blob/master/lib/index.js): validation gate · Coordinates credential checking with host-supplied logic · `lib/index.js`
- [Auth result](https://github.com/hapijs/basic/blob/master/lib/index.js): request outcome · Accepted identity or authentication failure returned to the host · `lib/index.js`
- [Package manifest](https://github.com/hapijs/basic/blob/master/package.json): package metadata · Node package metadata and entrypoint configuration · `package.json`

### Docs

Public contract and usage guidance

- [API contract](https://github.com/hapijs/basic/blob/master/API.md): reference · Package-level contract and behavior surface · `API.md`
- [Usage guide](https://github.com/hapijs/basic/blob/master/README.md): reference · Overview and integration examples for consumers · `README.md`

### Tests

Cross-format compatibility checks

- [CJS test](https://github.com/hapijs/basic/blob/master/test/index.js): test · CommonJS runtime coverage · `test/index.js`
- [TS test](https://github.com/hapijs/basic/blob/master/test/index.ts): test · TypeScript consumer coverage · `test/index.ts`
- [ESM test](https://github.com/hapijs/basic/blob/master/test/esm.js): test · ES module consumer coverage · `test/esm.js`

### CI

Automated library validation

- [CI workflow](https://github.com/hapijs/basic/blob/master/.github/workflows/ci-plugin.yml): pipeline · Automated validation for compatibility and correctness · `.github/workflows/ci-plugin.yml`

## Connections

- Client request → Host server: sends request · Client issues an HTTP request with Basic credentials
- Host server → Auth boundary: invokes auth · Server routes the request into the authentication boundary
- Auth boundary → Basic plugin: registers plugin · Host wires the library into its auth system
- Basic plugin → Header parse: parses header · Runtime reads and interprets the Authorization header
- Header parse → Validate creds: passes credentials · Parsed username and password move to validation coordination
- Validate creds → App validator: delegates check · Plugin asks host-defined logic to confirm identity
- App validator → Auth result: returns decision · Application supplies success or failure semantics
- Auth result → Host server: updates request · Server receives authenticated context or rejection
- API contract → Basic plugin: describes behavior · Documentation specifies the exported authentication contract
- Usage guide → Basic plugin: shows usage · README explains how consumers integrate the plugin
- Package manifest → Basic plugin: exposes entrypoint · Package metadata points consumers to the runtime implementation
- CJS test → Basic plugin: verifies · CommonJS test exercises the runtime entry
- TS test → API contract: verifies types · TypeScript test checks the public type surface
- ESM test → Basic plugin: verifies · ES module test exercises the runtime entry
- CI workflow → CJS test: runs · CI executes compatibility tests
- CI workflow → TS test: runs · CI executes TypeScript validation
- CI workflow → ESM test: runs · CI executes ES module validation
