# devwellington/brazilian-ddd-to-uf architecture

> Architecture diagram of the GitHub repository devwellington/brazilian-ddd-to-uf, 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/devwellington/brazilian-ddd-to-uf
- Repository: https://github.com/devwellington/brazilian-ddd-to-uf

## Overview

##### Project type and purpose
- This is an open-source PHP library (Composer package) whose sole responsibility is to convert Brazilian telephone DDD codes into state abbreviations (UF) or full state names, and to validate DDD codes.

##### File structure
- Top-level:
- composer.json, LICENSE, README.md – metadata and installation instructions
- examples/ – sample client code showing how to consume the library
- src/BrazilianDddToUF/ – all library code under a single namespace
- Under src/BrazilianDddToUF:
- AbstractBrazilianDddToUF.php – base class for conversion logic
- Convert/ – conversion implementations and interfaces
– ConvertDDD.php
– ConvertDDDtoUF.php
– ConvertDDDtoStateName.php
– IConvertDDDtoUF.php, IConvertDDDtoStateName.php
- Validate/ – validation logic
– Validate.php
– IValidate.php
- TraitValidator.php – shared input-validation utilities

##### README for additional insights
- Describes three conversion use-cases and one validation use-case
- Shows that the library exports static methods (e.g., getUF, getStateName, getArrayDDDandStateName, isValid)

a. Main components:
- Client Application (any PHP project that installs the package via Composer)
- Composer Autoloader (PSR-4 autoloading)
- BrazilianDddToUF Library
– Conversion Module
· ConvertDDDtoUF
· ConvertDDDtoStateName
· ConvertDDD
· AbstractBrazilianDddToUF (shared base logic, data mapping)
· Conversion interfaces
– Validation Module
· Validate
· IValidate
– TraitValidator (shared validation methods)
b. Relationships and interactions:
- Client → Composer Autoloader → Library classes
- Conversion Module ⇄ TraitValidator (validates input before conversion)
- Conversion classes extend AbstractBrazilianDddToUF to access the DDD-to-state mapping
- Validation Module uses TraitValidator to check DDD codes
- ConvertDDD may internally call both ConvertDDDtoUF and ConvertDDDtoStateName
c. Architectural patterns / design principles:
- Single Responsibility: separate Convert vs Validate
- Interface-based design: IConvert* and IValidate for extensibility
- Template/Abstract class for shared mapping data
- Trait for shared input validation
- Static-method façade simplifying client usage
d. Key technologies and libraries:
- PHP 5.4+
- Composer / PSR-4 autoloading

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External entities
    ClientApp["Client Application"]:::external
    Autoloader["Composer Autoloader"]:::external

    %% Library container
    subgraph "BrazilianDddToUF Library"
        direction TB
        %% Shared components
        Abstract["AbstractBrazilianDddToUF"]:::shared
        Trait["TraitValidator"]:::shared

        %% Conversion Module
        subgraph "Conversion Module"
            direction TB
            ConvDDD["ConvertDDD"]:::conversion
            ConvUF["ConvertDDDtoUF"]:::conversion
            ConvName["ConvertDDDtoStateName"]:::conversion
            IConvUF["IConvertDDDtoUF"]:::conversion
            IConvName["IConvertDDDtoStateName"]:::conversion
        end

        %% Validation Module
        subgraph "Validation Module"
            direction TB
            Validate["Validate"]:::validation
            IValidate["IValidate"]:::validation
        end
    end

    %% Relationships
    ClientApp -->|"getUF(), getStateName(), isValid()"|Autoloader
    Autoloader -->|"autoloads"|Abstract
    Autoloader -->|"autoloads"|Trait
    Autoloader -->|"autoloads"|ConvDDD
    Autoloader -->|"autoloads"|ConvUF
    Autoloader -->|"autoloads"|ConvName
    Autoloader -->|"autoloads"|IConvUF
    Autoloader -->|"autoloads"|IConvName
    Autoloader -->|"autoloads"|Validate
    Autoloader -->|"autoloads"|IValidate

    %% Conversion inheritance and usage
    ConvUF -->|"extends"|Abstract
    ConvName -->|"extends"|Abstract
    ConvDDD -->|"extends"|Abstract

    ConvUF -->|"implements"|IConvUF
    ConvName -->|"implements"|IConvName

    ConvDDD -->|"calls"|ConvUF
    ConvDDD -->|"calls"|ConvName

    ConvDDD -->|"uses"|Trait
    ConvUF -->|"uses"|Trait
    ConvName -->|"uses"|Trait

    %% Validation usage
    Validate -->|"implements"|IValidate
    Validate -->|"uses"|Trait

    %% Click Events
    click ClientApp "https://github.com/devwellington/brazilian-ddd-to-uf/blob/master/examples/index.php"
    click Autoloader "https://github.com/devwellington/brazilian-ddd-to-uf/blob/master/composer.json"
    click Library "https://github.com/devwellington/brazilian-ddd-to-uf/tree/master/src/BrazilianDddToUF"
    click Abstract "https://github.com/devwellington/brazilian-ddd-to-uf/blob/master/src/BrazilianDddToUF/AbstractBrazilianDddToUF.php"
    click Trait "https://github.com/devwellington/brazilian-ddd-to-uf/blob/master/src/BrazilianDddToUF/TraitValidator.php"
    click ConvDir "https://github.com/devwellington/brazilian-ddd-to-uf/tree/master/src/BrazilianDddToUF/Convert"
    click ConvDDD "https://github.com/devwellington/brazilian-ddd-to-uf/blob/master/src/BrazilianDddToUF/Convert/ConvertDDD.php"
    click ConvUF "https://github.com/devwellington/brazilian-ddd-to-uf/blob/master/src/BrazilianDddToUF/Convert/ConvertDDDtoUF.php"
    click ConvName "https://github.com/devwellington/brazilian-ddd-to-uf/blob/master/src/BrazilianDddToUF/Convert/ConvertDDDtoStateName.php"
    click IConvUF "https://github.com/devwellington/brazilian-ddd-to-uf/blob/master/src/BrazilianDddToUF/Convert/IConvertDDDtoUF.php"
    click IConvName "https://github.com/devwellington/brazilian-ddd-to-uf/blob/master/src/BrazilianDddToUF/Convert/IConvertDDDtoStateName.php"
    click ValDir "https://github.com/devwellington/brazilian-ddd-to-uf/tree/master/src/BrazilianDddToUF/Validate"
    click Validate "https://github.com/devwellington/brazilian-ddd-to-uf/blob/master/src/BrazilianDddToUF/Validate/Validate.php"
    click IValidate "https://github.com/devwellington/brazilian-ddd-to-uf/blob/master/src/BrazilianDddToUF/Validate/IValidate.php"

    %% Styles
    classDef conversion fill:#D0E9FF,stroke:#0366d6;
    classDef validation fill:#DFF5D0,stroke:#28a745;
    classDef shared fill:#F0F0F0,stroke:#888888;
    classDef external fill:#FFFFFF,stroke:#000000;
    classDef library fill:#FFF5E1,stroke:#E36C09;
    class Library shared
```
