# timiagama/nigerian-mobile-validator architecture

> Architecture diagram of the GitHub repository timiagama/nigerian-mobile-validator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/timiagama/nigerian-mobile-validator
- Repository: https://github.com/timiagama/nigerian-mobile-validator

## Overview

##### Project type and purpose
- This is an open-source, TypeScript‐based NPM library (“nigerian-mobile-validator”) whose sole purpose is to validate Nigerian mobile numbers against the NCC numbering plan. It’s not a full-stack app; it’s a modular tool intended for integration into other applications (fintech, telco, web, serverless, SSR, etc.).

##### File structure
- Top‐level: configuration files (.eslintrc.json, tsconfig*, jest.config.ts), CI/CD workflows (.github/workflows), docs, package.json
- src/ holds the library code, subdivided into:
- events/ (event emitter)
- logging/ (ILogger interface + implementations)
- number-validation/ (core validator interfaces and result types)
- numbering-plan/ (data model for ranges, network codes, telcos)
- security/ (ValidatorSecurity, rate limiting, sanitization)
- utils/ (runtime detection, general‐purpose utilities)
- index.ts exports public API (NigerianMobileNumberValidator, batchValidate, LoggerFactory, types)

##### README for additional insights
- Key features:
- Complete NCC compliance (data-driven lookups)
- Enterprise security (input sanitization, rate limiting)
- Reactive API (event emitter)
- Batch processing (array + file)
- Pluggable logging (Winston, Pino, console) with automatic PII masking
- Dual module support (ESM + CJS)
- SSR compatibility
- CI/CD integration with GitHub Actions (CodeQL, Snyk, SonarQube, Dependabot)

##### Main components
a. Core Validator Module
- NigerianMobileNumberValidator class (validate(), onValidationResult(), dispose())
- Uses sub‐modules in number‐validation/
b. Numbering Plan Data Module
- mobile-numbering-plan.ts, mobile-number-range.ts, network-access-code.ts, telco-number-allocation.ts
- Lazy‐loaded map/dictionary lookups of NCC data (source: docs/*.csv, .ods)
c. Security Module
- ValidatorSecurity: input sanitization, rate limiting, fast‐reject filters
d. Event Emitter
- event-emitter.ts: publishes validation results to listeners (reactive architecture)
e. Logging Module
- ILogger interface + LoggerFactory
- Adapters for console, Winston, Pino with PII masking wrappers
f. Batch Processing
- batchValidate functions (array API + fromFile) + CSV exporter
g. Utilities
- general-utils, runtime-environment detection for SSR vs. browser vs. Node
h. Public API Layer
- index.ts assembling and exporting all public classes, functions, types

##### Relationships and data flow
- Input (phone string) → Security Module (sanitize + rate limit) → Core Validator →
- Numbering Plan Data Module (look up network code, range, status) →
- Validation logic emits result objects →
- Logger Module (mask PII + output logs)
- Event Emitter (push result to subscribers) →
- Consumer receives result (synchronous return or async via event)
- Batch API: wraps multiple calls to Core Validator + aggregates results → optional CSV export

##### Architectural patterns and design principles
- Modular layering (Separation of concerns: security, validation logic, data, logging, eventing)
- Dependency Injection (ILogger implementations via LoggerFactory)
- Reactive pattern (Observer via event emitter)
- Data‐driven design (uses NCC data files as authoritative source)
- Strategy pattern (batch vs. single validation, ESM vs. CJS)

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Security & Utilities"
    direction TB
    sec["ValidatorSecurity"]:::infra
    util1["General Utilities"]:::infra
    util2["Runtime Environment Detection"]:::infra
  end

  subgraph "Validation Engine"
    direction TB
    core["NigerianMobileNumberValidator"]:::core
    iMobile["IMobileNumber Interface"]:::core
    resultType["ValidationResult Type"]:::core
    statusEnum["Validation Status Enum"]:::core
    triggerFlags["Validation Trigger Flags"]:::core
    directionType["Direction Typing"]:::core
  end

  subgraph "Numbering Plan Data"
    direction TB
    planLoader["Numbering Plan Loader"]:::data
    rangeModel["Mobile Number Range Model"]:::data
    nacModel["Network Access Code Model"]:::data
    allocationModel["Telco Allocation Model"]:::data
    telcoMeta["Telco Metadata"]:::data
  end

  subgraph "Logging & Events"
    direction TB
    loggerInt["ILogger Interface"]:::infra
    loggerFactory["LoggerFactory & Adapters"]:::infra
    emitter["Event Emitter"]:::infra
  end

  subgraph "Batch Processing & Public API"
    direction TB
    batch["Batch Validate API"]:::core
    publicAPI["Public API (index.ts)"]:::core
  end

  externalConsumer["Consumer Application"]:::external
  csvFS["File System (CSV)"]:::external

  externalConsumer -->|"input"| sec
  sec --> core
  util2 -->|"environment info"| core
  util1 -->|"utility functions"| core
  core -->|"lookup data"| planLoader
  planLoader --> rangeModel
  planLoader --> nacModel
  planLoader --> allocationModel
  planLoader --> telcoMeta
  core -->|"produces result"| loggerFactory
  core -->|"emits event"| emitter
  loggerFactory --> externalConsumer
  emitter --> externalConsumer
  batch --> core
  batch --> csvFS
  publicAPI --> core
  publicAPI --> batch
  externalConsumer --> publicAPI

  classDef core fill:#D0E6FF,stroke:#333,stroke-width:1px
  classDef infra fill:#E0F7E0,stroke:#333,stroke-width:1px
  classDef data fill:#FFF4B2,stroke:#333,stroke-width:1px
  classDef external fill:#F0F0F0,stroke-dasharray:5 5,stroke:#333,stroke-width:1px

  click core "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/number-validation/nigerian-mobile-number-validator.ts"
  click iMobile "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/number-validation/i-mobile-number.ts"
  click resultType "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/number-validation/mobile-number-validation-result.ts"
  click statusEnum "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/number-validation/mobile-validation-status.ts"
  click triggerFlags "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/number-validation/validation-triggering-flags.ts"
  click directionType "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/number-validation/typing-direction.ts"
  click rangeModel "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/numbering-plan/mobile-number-range.ts"
  click planLoader "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/numbering-plan/mobile-numbering-plan.ts"
  click nacModel "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/numbering-plan/network-access-code.ts"
  click allocationModel "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/numbering-plan/telco-number-allocation.ts"
  click telcoMeta "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/numbering-plan/telco.ts"
  click sec "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/security/validator-security.ts"
  click emitter "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/events/event-emitter.ts"
  click loggerInt "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/logging/i-logger.ts"
  click loggerFactory "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/logging/logger.ts"
  click batch "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/index.ts"
  click publicAPI "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/index.ts"
  click util1 "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/utils/general-utils.ts"
  click util2 "https://github.com/timiagama/nigerian-mobile-validator/blob/main/src/utils/runtime-environment.ts"
```
