# njprovk/creditscardtools architecture

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

- Interactive diagram: https://gitdiagram.com/njprovk/creditscardtools
- Repository: https://github.com/njprovk/creditscardtools

## Overview

1. **Repository type and boundary**
   - This is a **pure Python library**, not an application or service.
   - The runtime boundary is a small importable package, `card_generator`, whose public API is exposed through `__init__.py`.

2. **Primary domain**
   - The library focuses on **credit card number generation and validation**.
   - It supports common schemes such as Visa, MasterCard, Amex, and Discover, with generation constrained by card-brand rules and Luhn validity.

3. **Core package layout**
   - `card_generator/card_generator.py` contains the **generation logic**.
   - `card_generator/card_validator.py` contains the **validation and lookup logic**.
   - `card_generator/config.py` likely centralizes shared constants or scheme/BIN configuration used by both subsystems.

4. **Generation subsystem**
   - `CardGenerator` is the main abstraction for producing card records.
   - It generates:
     - the card number,
     - an expiry date,
     - a CVV,
     - optional formatting for the card string,
     - optional bank/BIN metadata.
   - The generator appears to support multiple outputs per call via a `count` argument.

5. **Validation subsystem**
   - `CardValidator` takes a card number and provides:
     - Luhn check validity,
     - card type detection,
     - BIN-based metadata lookup.
   - Validation is centered on static properties of the number rather than external verification.

6. **Offline BIN data layer**
   - `card_generator/bin-list-data.csv` is a bundled local dataset used for **BIN lookup**.
   - This is the main data boundary in the repository: generated or validated card numbers are mapped against this local file to derive brand, type, category, country, bank, and contact information.
   - The README makes clear that **no network access or API keys are needed at runtime**.

7. **Data flow across the library**
   - Input enters as a card scheme name or card number.
   - Generation creates candidate numbers and applies checksum rules.
   - Validation checks the number and, when possible, resolves BIN metadata from the CSV dataset.
   - Optional metadata is attached to generated results only when the BIN is found locally.

8. **Public API shape**
   - The package exports two main entry points:
     - `CardGenerator`
     - `CardValidator`
   - The README examples suggest the API is intentionally small and predictable, with simple methods/properties rather than a large framework.

9. **Testing boundary**
   - `tests/test_card_generator.py` and `tests/test_card_validator.py` cover the two main subsystems independently.
   - This mirrors the architecture: generation and validation are separate concerns, each with its own behavior and invariants.

10. **Packaging and dependency model**
   - `pyproject.toml` drives packaging and project metadata.
   - The project emphasizes being **dependency-free**, so the architecture is intentionally lightweight and self-contained.

11. **Quality and CI**
   - `.github/workflows/ci.yml` runs automated checks in GitHub Actions.
   - `.pre-commit-config.yaml` and `.flake8` indicate static quality gates are part of the workflow, supporting consistency for a small library codebase.

12. **How to draw the architecture**
   - Draw the package as a **single library box** with two internal modules: generator and validator.
   - Connect both modules to a shared **local BIN CSV data source**.
   - Show the public API as a thin facade over these modules.
   - Show tests and CI as separate quality/verification paths, not as runtime components.

Main entry points: [`card_generator/__init__.py`](https://github.com/njprovk/creditscardtools/blob/main/card_generator/__init__.py) (Public API), [`card_generator/card_generator.py`](https://github.com/njprovk/creditscardtools/blob/main/card_generator/card_generator.py) (Generator), [`card_generator/card_validator.py`](https://github.com/njprovk/creditscardtools/blob/main/card_generator/card_validator.py) (Validator), [`.github/workflows/ci.yml`](https://github.com/njprovk/creditscardtools/blob/main/.github/workflows/ci.yml) (CI workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime library"]
  node_pkg["card_generator<br/>package boundary"]
  node_api["Public API<br/>facade<br/>[__init__.py]"]
  node_gen["Generator<br/>card generation<br/>[card_generator.py]"]
  node_val["Validator<br/>card validation<br/>[card_validator.py]"]
  node_cfg["Config<br/>shared constants<br/>[config.py]"]
end

subgraph group_data["Local data"]
  node_bin[("BIN data<br/>offline csv<br/>[bin-list-data.csv]")]
end

subgraph group_verification["Verification"]
  node_gen_tests["Gen tests<br/>unit tests"]
  node_val_tests["Val tests<br/>unit tests"]
  node_ci["CI workflow<br/>automation<br/>[ci.yml]"]
  node_hooks["Quality gates<br/>lint hooks"]
end

subgraph group_project["Project assets"]
  node_readme["README<br/>usage docs<br/>[README.md]"]
  node_meta["Packaging<br/>project metadata<br/>[pyproject.toml]"]
end

node_pkg -->|"exports"| node_api
node_api -->|"wraps"| node_gen
node_api -->|"wraps"| node_val
node_gen -->|"uses"| node_cfg
node_gen -->|"enriches"| node_bin
node_val -->|"uses"| node_cfg
node_val -->|"looks up"| node_bin
node_readme -.->|"documents"| node_api
node_meta -->|"packages"| node_pkg
node_gen_tests -->|"verifies"| node_gen
node_val_tests -->|"verifies"| node_val
node_ci -->|"runs"| node_gen_tests
node_ci -->|"runs"| node_val_tests
node_ci -.->|"enforces"| node_hooks

click node_pkg "https://github.com/njprovk/creditscardtools/tree/main/card_generator"
click node_api "https://github.com/njprovk/creditscardtools/blob/main/card_generator/__init__.py"
click node_gen "https://github.com/njprovk/creditscardtools/blob/main/card_generator/card_generator.py"
click node_val "https://github.com/njprovk/creditscardtools/blob/main/card_generator/card_validator.py"
click node_cfg "https://github.com/njprovk/creditscardtools/blob/main/card_generator/config.py"
click node_bin "https://github.com/njprovk/creditscardtools/blob/main/card_generator/bin-list-data.csv"
click node_readme "https://github.com/njprovk/creditscardtools/blob/main/README.md"
click node_meta "https://github.com/njprovk/creditscardtools/blob/main/pyproject.toml"
click node_gen_tests "https://github.com/njprovk/creditscardtools/blob/main/tests/test_card_generator.py"
click node_val_tests "https://github.com/njprovk/creditscardtools/blob/main/tests/test_card_validator.py"
click node_ci "https://github.com/njprovk/creditscardtools/blob/main/.github/workflows/ci.yml"
click node_hooks "https://github.com/njprovk/creditscardtools/blob/main/.pre-commit-config.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_pkg,node_api,node_gen,node_val,node_cfg toneBlue
class node_bin toneAmber
class node_gen_tests,node_val_tests,node_ci,node_hooks toneMint
class node_readme,node_meta toneRose
```

## Components

### Runtime library

Importable package and core generation/validation logic.

- [card_generator](https://github.com/njprovk/creditscardtools/tree/main/card_generator): package boundary · Importable Python package exposing the library API. · `card_generator`
- [Public API](https://github.com/njprovk/creditscardtools/blob/main/card_generator/__init__.py): facade · Thin export surface for the library's main classes. · `card_generator/__init__.py`
- [Generator](https://github.com/njprovk/creditscardtools/blob/main/card_generator/card_generator.py): card generation · Produces card numbers and related card records. · `card_generator/card_generator.py`
- [Validator](https://github.com/njprovk/creditscardtools/blob/main/card_generator/card_validator.py): card validation · Checks numbers, identifies card type, and resolves BIN metadata. · `card_generator/card_validator.py`
- [Config](https://github.com/njprovk/creditscardtools/blob/main/card_generator/config.py): shared constants · Central configuration and scheme rules used by both subsystems. · `card_generator/config.py`

### Local data

Bundled offline lookup data used by validation and metadata enrichment.

- [BIN data](https://github.com/njprovk/creditscardtools/blob/main/card_generator/bin-list-data.csv): offline csv · Bundled local BIN dataset for brand and issuer lookup. · `card_generator/bin-list-data.csv`

### Verification

Tests and automated quality gates.

- [Gen tests](https://github.com/njprovk/creditscardtools/blob/main/tests/test_card_generator.py): unit tests · Tests generation rules and output structure. · `tests/test_card_generator.py`
- [Val tests](https://github.com/njprovk/creditscardtools/blob/main/tests/test_card_validator.py): unit tests · Tests validation, lookup, and card type detection. · `tests/test_card_validator.py`
- [CI workflow](https://github.com/njprovk/creditscardtools/blob/main/.github/workflows/ci.yml): automation · GitHub Actions workflow for automated checks. · `.github/workflows/ci.yml`
- [Quality gates](https://github.com/njprovk/creditscardtools/blob/main/.pre-commit-config.yaml): lint hooks · Pre-commit and linting rules that enforce code quality. · `.pre-commit-config.yaml`

### Project assets

Packaging and documentation boundaries.

- [README](https://github.com/njprovk/creditscardtools/blob/main/README.md): usage docs · Examples and behavioral overview of the library. · `README.md`
- [Packaging](https://github.com/njprovk/creditscardtools/blob/main/pyproject.toml): project metadata · Build and dependency metadata for the library package. · `pyproject.toml`

## Connections

- card_generator → Public API: exports · Package exposes the public classes through its top-level module.
- Public API → Generator: wraps · Public API surfaces the generator entry point.
- Public API → Validator: wraps · Public API surfaces the validator entry point.
- Generator → Config: uses · Generator consumes shared scheme and generation rules.
- Generator → BIN data: enriches · Generated card records can include issuer metadata from local BIN data.
- Validator → Config: uses · Validator relies on shared card rules and constants.
- Validator → BIN data: looks up · Validator resolves BIN-derived metadata from the bundled dataset.
- README → Public API: documents · README shows the intended small public API and usage flow.
- Packaging → card_generator: packages · Project metadata defines the installable library boundary.
- Gen tests → Generator: verifies · Unit tests cover generation behavior and invariants.
- Val tests → Validator: verifies · Unit tests cover validation and metadata lookup.
- CI workflow → Gen tests: runs · CI executes generator tests as part of the check pipeline.
- CI workflow → Val tests: runs · CI executes validator tests as part of the check pipeline.
- CI workflow → Quality gates: enforces · CI complements local lint and pre-commit quality gates.