# geoffgarside/pwnedpassword architecture

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

- Interactive diagram: https://gitdiagram.com/geoffgarside/pwnedpassword
- Repository: https://github.com/geoffgarside/pwnedpassword

## Overview

1. This is a small Go module centered on a reusable password-checking library plus a thin command-line wrapper. The repository root contains the core package (`pwnedpassword.go`) and its tests, while `cmd/pwnedpassword` holds the executable entrypoint.

2. The primary architectural boundary is:
   - **Core library**: reusable password validation/check logic.
   - **CLI application**: terminal UX for prompting the user and printing the result.
   This separation makes the password-checking logic consumable from other Go programs, not just the included binary.

3. The user-facing flow is simple:
   - the CLI prompts for a password from the terminal,
   - passes the entered secret into the library,
   - the library checks whether the password appears in the breached-password dataset/service,
   - the CLI reports the outcome to the user and exits.

4. The repository name and README indicate the library is meant for the **Pwned Passwords** service/use case, so the core responsibility is checking whether a password has been exposed in known breaches. Any network/API interaction is likely encapsulated inside the root package rather than the command package.

5. `cmd/pwnedpassword/main.go` is the only production binary. That file should be treated as the orchestration layer: argument/terminal handling, invoking the library, and formatting the final result. It should not own the checking algorithm itself.

6. The root package (`pwnedpassword.go`) is the main domain layer. This is where the repo’s important logic lives: input normalization, password lookup/checking, and any response interpretation. If you are drawing the diagram, this package is the central service node.

7. Tests are split between package-level and internal tests:
   - `pwnedpassword_test.go` likely exercises the public API,
   - `pwnedpassword_internal_test.go` likely covers private helpers or edge cases,
   - `cmd/pwnedpassword/main_test.go` validates CLI behavior.
   This indicates the repo values both library correctness and command behavior separately.

8. The project uses standard Go tooling and packaging:
   - `go.mod` / `go.sum` define dependencies and module boundaries,
   - GitHub Actions (`.github/workflows/go.yaml`) runs CI for build/test automation.
   There are no signs of containers, databases, or background services; this is a self-contained Go utility with an external password-check service as the only meaningful runtime dependency.

9. In diagram terms, the architecture is best represented as a **single core library with one presentation adapter**:
   - External user/terminal input enters the CLI,
   - CLI calls the library,
   - library performs the breach check,
   - result returns to the CLI and then to the terminal.
   The boundary between CLI and library is the key one to emphasize.

Main entry points: [`cmd/pwnedpassword/main.go`](https://github.com/geoffgarside/pwnedpassword/blob/master/cmd/pwnedpassword/main.go) (CLI entrypoint), [`pwnedpassword.go`](https://github.com/geoffgarside/pwnedpassword/blob/master/pwnedpassword.go) (Password check), [`.github/workflows/go.yaml`](https://github.com/geoffgarside/pwnedpassword/blob/master/.github/workflows/go.yaml) (CI workflow), [`go.mod`](https://github.com/geoffgarside/pwnedpassword/blob/master/go.mod) (Module files)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Core library"]
  node_node_core["Password check<br/>go library<br/>[pwnedpassword.go]"]
  node_node_lookup["Breach lookup<br/>check flow<br/>[pwnedpassword.go]"]
  node_node_lib_tests["Library tests<br/>go tests"]
end

subgraph group_group_cli["CLI app"]
  node_node_cli_main["CLI entrypoint<br/>go command<br/>[main.go]"]
  node_node_cli_tests["CLI tests<br/>go tests<br/>[main_test.go]"]
end

subgraph group_group_ci["Tooling"]
  node_node_go_mod["Module files<br/>go module<br/>[go.mod]"]
  node_node_ci["CI workflow<br/>automation<br/>[go.yaml]"]
end

node_node_terminal(("Terminal user<br/>external actor"))

node_node_terminal -->|"enter password"| node_node_cli_main
node_node_cli_main -->|"invoke check"| node_node_core
node_node_core -->|"perform lookup"| node_node_lookup
node_node_lookup -->|"return result"| node_node_cli_main
node_node_cli_main -->|"print status"| node_node_terminal
node_node_lib_tests -.->|"verify"| node_node_core
node_node_cli_tests -.->|"verify"| node_node_cli_main
node_node_go_mod -.->|"defines deps"| node_node_core
node_node_go_mod -.->|"defines deps"| node_node_cli_main
node_node_ci -.->|"run tests"| node_node_lib_tests
node_node_ci -.->|"run tests"| node_node_cli_tests
node_node_ci -.->|"use module"| node_node_go_mod

click node_node_cli_main "https://github.com/geoffgarside/pwnedpassword/blob/master/cmd/pwnedpassword/main.go"
click node_node_core "https://github.com/geoffgarside/pwnedpassword/blob/master/pwnedpassword.go"
click node_node_lookup "https://github.com/geoffgarside/pwnedpassword/blob/master/pwnedpassword.go"
click node_node_lib_tests "https://github.com/geoffgarside/pwnedpassword/blob/master/pwnedpassword_test.go"
click node_node_cli_tests "https://github.com/geoffgarside/pwnedpassword/blob/master/cmd/pwnedpassword/main_test.go"
click node_node_go_mod "https://github.com/geoffgarside/pwnedpassword/blob/master/go.mod"
click node_node_ci "https://github.com/geoffgarside/pwnedpassword/blob/master/.github/workflows/go.yaml"

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_node_core,node_node_lookup,node_node_lib_tests toneBlue
class node_node_cli_main,node_node_cli_tests toneAmber
class node_node_go_mod,node_node_ci toneMint
class node_node_terminal toneNeutral
```

## Components

### Core library

Reusable password-breach checking logic in the root package.

- [Password check](https://github.com/geoffgarside/pwnedpassword/blob/master/pwnedpassword.go): go library · Main domain package for checking whether a password has been exposed. · `pwnedpassword.go`
- [Breach lookup](https://github.com/geoffgarside/pwnedpassword/blob/master/pwnedpassword.go): check flow · Normalizes input and performs the breached-password query or response interpretation. · `pwnedpassword.go`
- [Library tests](https://github.com/geoffgarside/pwnedpassword/blob/master/pwnedpassword_test.go): go tests · Package-level and internal tests covering the reusable core logic. · `pwnedpassword_test.go`

### CLI app

Thin terminal wrapper around the core library.

- [CLI entrypoint](https://github.com/geoffgarside/pwnedpassword/blob/master/cmd/pwnedpassword/main.go): go command · Orchestrates prompting, calling the library, and printing the outcome. · `cmd/pwnedpassword/main.go`
- [CLI tests](https://github.com/geoffgarside/pwnedpassword/blob/master/cmd/pwnedpassword/main_test.go): go tests · Tests validating command behavior and terminal-facing output. · `cmd/pwnedpassword/main_test.go`

### Tooling

Module and CI automation for builds and tests.

- [Module files](https://github.com/geoffgarside/pwnedpassword/blob/master/go.mod): go module · Module boundary and dependency definitions. · `go.mod`
- [CI workflow](https://github.com/geoffgarside/pwnedpassword/blob/master/.github/workflows/go.yaml): automation · GitHub Actions workflow for build and test automation. · `.github/workflows/go.yaml`

### Other components

- **Terminal user**: external actor · Person entering a password and reading the result.

## Connections

- Terminal user → CLI entrypoint: enter password · User input enters the command-line interface.
- CLI entrypoint → Password check: invoke check · The CLI delegates password validation to the reusable library.
- Password check → Breach lookup: perform lookup · Core logic executes the breach-checking flow.
- Breach lookup → CLI entrypoint: return result · The library returns the check outcome to the CLI.
- CLI entrypoint → Terminal user: print status · The CLI reports the final result back to the user.
- Library tests → Password check: verify · Tests exercise the public and internal library behavior.
- CLI tests → CLI entrypoint: verify · Tests exercise command-line orchestration and output.
- Module files → Password check: defines deps · Module metadata governs the library package and its dependencies.
- Module files → CLI entrypoint: defines deps · Module metadata governs the command binary and its dependencies.
- CI workflow → Library tests: run tests · CI builds and tests the repository.
- CI workflow → CLI tests: run tests · CI includes command behavior validation.
- CI workflow → Module files: use module · Automation operates within the Go module boundary.