How geoffgarside/pwnedpassword works
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: main.go CLI entrypoint · pwnedpassword.go Password check · go.yaml CI workflow · go.mod Module files
Components 8
Core library
Reusable password-breach checking logic in the root package.
- Password check · Main domain package for checking whether a password has been exposed.
pwnedpassword.go - Breach lookup · Normalizes input and performs the breached-password query or response interpretation.
pwnedpassword.go - Library 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 · Orchestrates prompting, calling the library, and printing the outcome.
cmd/pwnedpassword/main.go - CLI 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 · Module boundary and dependency definitions.
go.mod - CI workflow · GitHub Actions workflow for build and test automation.
.github/workflows/go.yaml
Other components
- Terminal user · Person entering a password and reading the result.
Connections 12
- 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.