# houbb/sensitive-word architecture

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

- Interactive diagram: https://gitdiagram.com/houbb/sensitive-word
- Repository: https://github.com/houbb/sensitive-word

## Overview

sensitive-word is a Java library for detecting and masking sensitive text with a DFA-based matcher. The main workflow is: an application configures and initializes the fluent builder, submits text for matching, then receives a containment answer, matched words, or replacement text. Configuration supports formatting variants, allow/deny lists, specialized checks, ignored characters, and tags; result handlers shape match output. The graph combines sampled implementation references with README-documented capabilities. Some implementation details are unsampled, so documented but unverified links are dashed.

Main entry points: [`src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordBs.java`](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordBs.java) (Fluent builder), [`src/main/java/com/github/houbb/sensitive/word/core/SensitiveWord.java`](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/core/SensitiveWord.java) (DFA matcher), [`src/main/java/com/github/houbb/sensitive/word/core/SensitiveWordHelper.java`](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/core/SensitiveWordHelper.java) (Convenience API), [`src/main/java/com/github/houbb/sensitive/word/support/result/WordResult.java`](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/result/WordResult.java) (Match results)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Configuration and API"]
  node_builder["Fluent builder"]
  node_context["Runtime context"]
  node_helper["Convenience API"]
end

subgraph group_matching["Matching and dictionaries"]
  node_matcher["DFA matcher<br/>[SensitiveWord.java]"]
  node_matcher_base["Matcher base"]
  node_dict[("Deny dictionary<br/>[WordDataTree.java]")]
  node_allow["Allow dictionary<br/>[WordAllows.java]"]
end

subgraph group_policies["Normalization and policies"]
  node_word_checks["Word checks<br/>[WordCheckWord.java]"]
  node_other_checks["Special checks<br/>[WordChecks.java]"]
  node_format["Format variants<br/>[WordFormats.java]"]
  node_format_text["Text mappings"]
  node_char_ignore["Character skipping"]
  node_tags["Word tags<br/>[WordTags.java]"]
end

subgraph group_output["Results and masking"]
  node_results["Match results<br/>[WordResult.java]"]
  node_handlers["Result handlers"]
  node_replace["Replacement<br/>[WordReplaces.java]"]
end

node_application(("Application"))

node_application -->|"configures"| node_builder
node_application -->|"submits text"| node_helper
node_builder -->|"builds context"| node_context
node_builder -->|"initializes words"| node_dict
node_builder -->|"configures allowlist"| node_allow
node_builder -->|"dispatches searches"| node_matcher
node_builder -->|"returns matches"| node_results
node_helper -.->|"uses defaults"| node_builder
node_matcher -->|"extends"| node_matcher_base
node_matcher -->|"queries words"| node_dict
node_matcher -->|"reads settings"| node_context
node_matcher -->|"checks candidates"| node_word_checks
node_matcher -->|"creates matches"| node_results
node_matcher -->|"normalizes input"| node_format
node_builder -->|"selects formats"| node_format
node_builder -.->|"configures mappings"| node_format_text
node_builder -->|"configures skipping"| node_char_ignore
node_builder -->|"selects checks"| node_other_checks
node_builder -->|"configures tags"| node_tags
node_results -->|"processed by"| node_handlers
node_handlers -->|"looks up tags"| node_tags
node_builder -.->|"selects strategy"| node_replace
node_helper -.->|"finds matches"| node_results
node_helper -.->|"masks text"| node_replace

click node_builder "https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordBs.java"
click node_context "https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordContext.java"
click node_matcher "https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/core/SensitiveWord.java"
click node_matcher_base "https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/core/AbstractSensitiveWord.java"
click node_dict "https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/data/WordDataTree.java"
click node_allow "https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/allow/WordAllows.java"
click node_word_checks "https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/check/WordCheckWord.java"
click node_other_checks "https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/check/WordChecks.java"
click node_format "https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/format/WordFormats.java"
click node_format_text "https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/format/mapping/WordFormatTexts.java"
click node_char_ignore "https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/ignore/SensitiveWordCharIgnores.java"
click node_tags "https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/tag/WordTags.java"
click node_results "https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/result/WordResult.java"
click node_handlers "https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/result/WordResultHandlers.java"
click node_replace "https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/replace/WordReplaces.java"
click node_helper "https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/core/SensitiveWordHelper.java"

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_builder,node_context,node_helper toneBlue
class node_matcher,node_matcher_base,node_dict,node_allow toneAmber
class node_word_checks,node_other_checks,node_format,node_format_text,node_char_ignore,node_tags toneMint
class node_results,node_handlers,node_replace toneRose
class node_application toneIndigo
```

## Components

### Configuration and API

- [Fluent builder](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordBs.java): `src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordBs.java`
- [Runtime context](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordContext.java): `src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordContext.java`
- [Convenience API](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/core/SensitiveWordHelper.java): `src/main/java/com/github/houbb/sensitive/word/core/SensitiveWordHelper.java`

### Matching and dictionaries

- [DFA matcher](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/core/SensitiveWord.java): `src/main/java/com/github/houbb/sensitive/word/core/SensitiveWord.java`
- [Matcher base](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/core/AbstractSensitiveWord.java): `src/main/java/com/github/houbb/sensitive/word/core/AbstractSensitiveWord.java`
- [Deny dictionary](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/data/WordDataTree.java): `src/main/java/com/github/houbb/sensitive/word/support/data/WordDataTree.java`
- [Allow dictionary](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/allow/WordAllows.java): `src/main/java/com/github/houbb/sensitive/word/support/allow/WordAllows.java`

### Normalization and policies

- [Word checks](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/check/WordCheckWord.java): `src/main/java/com/github/houbb/sensitive/word/support/check/WordCheckWord.java`
- [Special checks](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/check/WordChecks.java): `src/main/java/com/github/houbb/sensitive/word/support/check/WordChecks.java`
- [Format variants](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/format/WordFormats.java): `src/main/java/com/github/houbb/sensitive/word/support/format/WordFormats.java`
- [Text mappings](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/format/mapping/WordFormatTexts.java): `src/main/java/com/github/houbb/sensitive/word/support/format/mapping/WordFormatTexts.java`
- [Character skipping](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/ignore/SensitiveWordCharIgnores.java): `src/main/java/com/github/houbb/sensitive/word/support/ignore/SensitiveWordCharIgnores.java`
- [Word tags](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/tag/WordTags.java): `src/main/java/com/github/houbb/sensitive/word/support/tag/WordTags.java`

### Results and masking

- [Match results](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/result/WordResult.java): `src/main/java/com/github/houbb/sensitive/word/support/result/WordResult.java`
- [Result handlers](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/result/WordResultHandlers.java): `src/main/java/com/github/houbb/sensitive/word/support/result/WordResultHandlers.java`
- [Replacement](https://github.com/houbb/sensitive-word/blob/master/src/main/java/com/github/houbb/sensitive/word/support/replace/WordReplaces.java): `src/main/java/com/github/houbb/sensitive/word/support/replace/WordReplaces.java`

### Other components

- **Application**

## Connections

- Application → Fluent builder: configures (evidence: `README.md`)
- Application → Convenience API: submits text (evidence: `README.md`)
- Fluent builder → Runtime context: builds context (evidence: `src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordBs.java`)
- Fluent builder → Deny dictionary: initializes words (evidence: `src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordBs.java`)
- Fluent builder → Allow dictionary: configures allowlist (evidence: `src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordBs.java`)
- Fluent builder → DFA matcher: dispatches searches (evidence: `src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordBs.java`)
- Fluent builder → Match results: returns matches (evidence: `src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordBs.java`)
- Convenience API → Fluent builder: uses defaults (evidence: `README.md`)
- DFA matcher → Matcher base: extends (evidence: `src/main/java/com/github/houbb/sensitive/word/core/SensitiveWord.java`)
- DFA matcher → Deny dictionary: queries words (evidence: `src/main/java/com/github/houbb/sensitive/word/core/SensitiveWord.java`)
- DFA matcher → Runtime context: reads settings (evidence: `src/main/java/com/github/houbb/sensitive/word/core/SensitiveWord.java`)
- DFA matcher → Word checks: checks candidates (evidence: `src/main/java/com/github/houbb/sensitive/word/support/check/WordCheckWord.java`)
- DFA matcher → Match results: creates matches (evidence: `src/main/java/com/github/houbb/sensitive/word/core/SensitiveWord.java`)
- DFA matcher → Format variants: normalizes input (evidence: `src/main/java/com/github/houbb/sensitive/word/core/SensitiveWord.java`)
- Fluent builder → Format variants: selects formats (evidence: `src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordBs.java`)
- Fluent builder → Text mappings: configures mappings (evidence: `src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordBs.java`)
- Fluent builder → Character skipping: configures skipping (evidence: `src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordBs.java`)
- Fluent builder → Special checks: selects checks (evidence: `src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordBs.java`)
- Fluent builder → Word tags: configures tags (evidence: `src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordBs.java`)
- Match results → Result handlers: processed by (evidence: `README.md`)
- Result handlers → Word tags: looks up tags
- Fluent builder → Replacement: selects strategy (evidence: `src/main/java/com/github/houbb/sensitive/word/bs/SensitiveWordBs.java`)
- Convenience API → Match results: finds matches (evidence: `README.md`)
- Convenience API → Replacement: masks text (evidence: `README.md`)
