# gookit/validate architecture

> Architecture diagram of the GitHub repository gookit/validate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gookit/validate
- Repository: https://github.com/gookit/validate

## Overview

##### Project Type and Purpose
- This is an open-source Go library (not a standalone app) for data validation and filtering.
- It provides generic routines to validate/map/sanitize data from maps, structs, HTTP requests, JSON, form values, etc.
- Key use-cases: struct-tag driven validation, map-based validation, request payload validation, custom rules/filters and i18n error messages.

##### File Structure Analysis
- Top-level files and dirs:
- go.mod / go.sum – Go module definitions
- cache.go, filtering.go, validate.go, validating.go, validation.go, data_source.go, rule.go, validators.go, util.go, value.go, messages.go
– core packages implementing filters, rules, validation engine, data sources, utilities and messaging
- locales/** – i18n packages (en, zh-CN, zh-TW, ruru)
- _examples/** – sample code (httpdemo, request usage, etc.)
- docs/** – extended documentation (diffs, built-in rules list)
- test files & testdata/ – unit tests and fixtures
- .github/**, CI/YAML – GitHub Actions, Dependabot, issue templates, changelog
- index.html – project homepage
- Patterns & modules:
- DataFace abstraction → MapData, StructData, FormData
- Validation core (Validation struct) → rule parsing, filter execution, error collection
- Registry pattern for built-in/custom validators and filters
- GlobalOption for global configuration
- i18n via locales packages

##### Insights from README
- Main features: validate Map, Struct, Request; add custom filters/validators; scene support; custom error messages; built-in 70+ validators; filtering/sanitization.
- Integration points: any Go web framework (e.g., Gin, Echo, Chi) by supplying a custom binding validator.
- Extension points: validate.AddValidator/AddFilter (global), v.AddValidator/v.AddFilter (per-instance).

a. Main Components
1. Data Sources (DataFace layer)
- MapData
- StructData
- FormData (URL values, JSON, multipart)
2. Filter Engine
- Built-in filters (gookit/filter)
- Custom filter registry
3. Validation Engine (Validation struct)
- Rule parser
- Rule registry (built-in & custom validators)
- GlobalOption configuration
- Scene management
4. Message & i18n
- Messages.go (default English)
- locales packages (zh-CN, zh-TW, ruru)
- Custom message/label tags and struct methods
5. Error Handling
- Errors collection (Errors type)
- JSON marshal behavior (StopOnError, multi-error)
6. Integration Layer
- HTTP request adapter (validate.FromRequest)
- Framework binding (Gin/Echo custom StructValidator)
7. Examples & Documentation
- _examples
- docs

b. Relationships and Data Flow
- Input data (map/struct/HTTP request) → DataFace
- DataFace.Create() → Validation instance
- Validation pipeline:
1. apply filters → sanitized data
2. apply rules → boolean checks
3. collect errors if any
- Upon success: v.SafeData() / v.BindSafeData() → user struct
- Error output → Errors struct → API response or returned error
- GlobalOption → influences filter/rule engine behavior
- Custom validators/filters registered at startup or per request

c. Architectural Patterns & Principles
- Layered design: DataFace → Validation → Error
- Registry pattern: plug-in validators & filters
- Strategy pattern: filter & validator functions passed around
- Dependency injection via interfaces (DataFace)
- Single responsibility: each package/file has clear role (data source, filter, validation, messaging)
- Extensibility: clear extension points for custom rules, filters, messages, locales

d. Technologies and Frameworks
- Go modules (go.mod)
- Standard library (net/http, time)
- Third-party: gookit/filter, any Go web framework (Gin, Echo, Chi)
- CI: GitHub Actions (Go test, codeql)
- i18n packages under locales/

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Modules
    subgraph "Core Modules"
        DataSource["DataFace Layer"]:::core
        FilterEngine["Filter Engine"]:::core
        ValidationEngine["Validation Engine"]:::core
    end

    %% Rule Module
    subgraph "Rule Module"
        RuleRegistry[(Rule Registry)]:::core
    end

    %% Message & i18n
    subgraph "Message & i18n"
        Messages["Messages"]:::i18n
        Locales[(Locales)]:::i18n
    end

    %% Error Handling
    ErrorHandling["Error Handling"]:::core

    %% Integration Adapter
    subgraph "Integration Adapter"
        HTTPAdapter["HTTP & Framework Adapter"]:::integration
        ExternalFW1(["Gin"]):::external
        ExternalFW2(["Echo"]):::external
        ExternalFW3(["Chi"]):::external
    end

    %% Examples & Docs
    subgraph "Examples & Docs"
        Examples["Examples"]:::docs
        Docs["Documentation"]:::docs
    end

    %% CI/CD & Metadata
    subgraph "CI/CD & Metadata"
        Workflows["GitHub Workflows"]:::ci
        Modules["Go Modules"]:::ci
        Tests["Tests & Fixtures"]:::ci
    end

    %% Data Flow
    Input["Input Data (map/struct/HTTP)"]:::external --> DataSource
    DataSource --> ValidationEngine
    ValidationEngine --> FilterEngine
    FilterEngine --> RuleRegistry
    RuleRegistry --> ErrorHandling
    ErrorHandling --> Output["SafeData or Errors"]:::external

    %% Integration Flow
    HTTPAdapter --> DataSource
    HTTPAdapter --> ValidationEngine
    ExternalFW1 --> HTTPAdapter
    ExternalFW2 --> HTTPAdapter
    ExternalFW3 --> HTTPAdapter

    %% GlobalOption & Custom Registry
    GlobalOption["GlobalOption"]:::extension
    CustomRegistry["Custom Filters/Validators"]:::extension
    GlobalOption --> ValidationEngine
    GlobalOption --> FilterEngine
    CustomRegistry --> RuleRegistry
    CustomRegistry --> FilterEngine

    %% Examples & Docs Connections
    Examples -.-> ValidationEngine
    Docs -.-> ValidationEngine

    %% CI/CD & Metadata Connections
    Workflows -.-> ValidationEngine
    Modules -.-> ValidationEngine
    Tests -.-> ValidationEngine

    %% Legend
    subgraph Legend
      A["Core Modules"]:::core
      B["Extension Points"]:::extension
      C["Localization"]:::i18n
      D["Integration"]:::integration
      E["External"]:::external
      F["Documentation & Examples"]:::docs
      G["CI/CD & Metadata"]:::ci
    end

    %% Click Events
    click DataSource "https://github.com/gookit/validate/blob/master/data_source.go"
    click FilterEngine "https://github.com/gookit/validate/blob/master/filtering.go"
    click FilterEngine "https://github.com/gookit/validate/blob/master/util.go"
    click ValidationEngine "https://github.com/gookit/validate/blob/master/validation.go"
    click ValidationEngine "https://github.com/gookit/validate/blob/master/validating.go"
    click ValidationEngine "https://github.com/gookit/validate/blob/master/validate.go"
    click RuleRegistry "https://github.com/gookit/validate/blob/master/rule.go"
    click RuleRegistry "https://github.com/gookit/validate/blob/master/validators.go"
    click RuleRegistry "https://github.com/gookit/validate/blob/master/register.go"
    click Messages "https://github.com/gookit/validate/blob/master/messages.go"
    click Locales "https://github.com/gookit/validate/tree/master/locales/zhcn"
    click Locales "https://github.com/gookit/validate/tree/master/locales/zhtw"
    click Locales "https://github.com/gookit/validate/tree/master/locales/ruru"
    click ErrorHandling "https://github.com/gookit/validate/blob/master/validating.go"
    click HTTPAdapter "https://github.com/gookit/validate/blob/master/validate.go"
    click HTTPAdapter "https://github.com/gookit/validate/blob/master/register.go"
    click Examples "https://github.com/gookit/validate/tree/master/_examples/"
    click Docs "https://github.com/gookit/validate/tree/master/docs/"
    click Workflows "https://github.com/gookit/validate/tree/master/.github/workflows/"
    click Modules "https://github.com/gookit/validate/blob/master/go.mod"
    click Modules "https://github.com/gookit/validate/blob/master/go.sum"
    click Tests "https://github.com/gookit/validate/tree/master/testdata/"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#2980B9,stroke-width:1px
    classDef extension fill:#D5F5E3,stroke:#27AE60,stroke-width:1px
    classDef i18n fill:#FCF3CF,stroke:#F1C40F,stroke-width:1px
    classDef integration fill:#F4ECF7,stroke:#8E44AD,stroke-width:1px
    classDef external fill:#FADBD8,stroke:#C0392B,stroke-width:1px
    classDef docs fill:#EBEFFB,stroke:#5D6D7E,stroke-width:1px
    classDef ci fill:#FDEDEC,stroke:#E74C3C,stroke-width:1px
```
