# drafthouse/addressing architecture

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

- Interactive diagram: https://gitdiagram.com/drafthouse/addressing
- Repository: https://github.com/drafthouse/addressing

## Overview

##### Main Components Identification
The system should be divided into these core components:

a) Core Address Components:
- Address Format System
- Subdivision System
- Country System
- Validation System
- Formatting System
- Zone System

b) Data Storage:
- JSON Resources Repository
- Format Definitions
- Subdivision Data
- Country Data

##### Component Relationships

**[Data Layer]**
- ↑
**[Core Services Layer]**
- ↑
**[Formatter Layer]**
- ↑
**[Validation Layer]**

##### Specific Implementation Details

a) Address Format Component:
- AddressFormat Repository
- Format Definitions
- Field Specifications
- Required Fields Logic

b) Subdivision Component:
- Hierarchical Structure
- Three-level Support (Administrative Area → Locality → Dependent Locality)
- Subdivision Repository
- Lazy Loading Collection

c) Formatter Component:
- Default Formatter
- Postal Label Formatter
- HTML/Text Output Support

d) Validator Component:
- Symfony Validator Integration
- Format Constraints
- Country Constraints
- Postal Code Validation

e) Zone Component:
- Territory Management
- Matching Logic
- Postal Code Ranges
- Country/Region Groups

##### Flow Representation

**[JSON Resources] → [Repositories] → [Services] → [Formatters/Validators]**

##### Integration Points

External integration points:
- Symfony Validator
- Postal Systems
- Country Standards
- Address Format Standards

##### Technical Details

Technical specifications:
- PHP 5.5+ requirement
- JSON data format
- OASIS xAL standard compliance
- Google's Address Data Service origin

- Data storage (JSON resources)
- Core services (Address, Format, Subdivision handling)
- Presentation (Formatters)
- Validation (Constraints)
- Territory management (Zones)

This will create a comprehensive visualization that accurately represents the library's architecture while maintaining clarity and usefulness for development purposes.

Remember to maintain a balance between detail and clarity, focusing on the key architectural decisions that make this library effective for address handling across different countries and formats.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Data
        JSON[("JSON Resources")]
        SubdivisionData[("Subdivision Data")]
        FormatData[("Format Definitions")]
        CountryData[("Country Data")]
    end

    subgraph Core
        AddressFormat["Address Format System"]
        AFRepo["Format Repository"]
        Subdivision["Subdivision System"]
        SubRepo["Subdivision Repository"]
        Country["Country System"]
        CountryRepo["Country Repository"]
        Zone["Zone System"]
        ZoneTerritory["Territory Handler"]
    end

    subgraph Formatter
        DefaultF["Default Formatter"]
        PostalF["Postal Label Formatter"]
    end

    subgraph Validator
        FormatV["Format Validator"]
        CountryV["Country Validator"]
        Constraints["Validation Constraints"]
    end

    %% Data Flow
    JSON --> AFRepo
    JSON --> SubRepo
    JSON --> CountryRepo
    SubdivisionData --> SubRepo
    FormatData --> AFRepo
    CountryData --> CountryRepo

    %% Core Relationships
    AFRepo --> AddressFormat
    SubRepo --> Subdivision
    CountryRepo --> Country
    Zone --> ZoneTerritory

    %% Service Flow
    AddressFormat --> DefaultF
    AddressFormat --> PostalF
    Subdivision --> DefaultF
    Country --> DefaultF
    
    AddressFormat --> FormatV
    Country --> CountryV
    Constraints --> FormatV
    Constraints --> CountryV

    %% Styling
    classDef data fill:#90EE90
    classDef core fill:#87CEEB
    classDef formatter fill:#FFB6C1
    classDef validator fill:#DDA0DD

    class JSON,SubdivisionData,FormatData,CountryData data
    class AddressFormat,AFRepo,Subdivision,SubRepo,Country,CountryRepo,Zone,ZoneTerritory core
    class DefaultF,PostalF formatter
    class FormatV,CountryV,Constraints validator

    %% Click Events
    click AddressFormat "https://github.com/drafthouse/addressing/tree/master/src/AddressFormat/"
    click AFRepo "https://github.com/drafthouse/addressing/blob/master/src/AddressFormat/AddressFormatRepository.php"
    click Subdivision "https://github.com/drafthouse/addressing/tree/master/src/Subdivision/"
    click SubRepo "https://github.com/drafthouse/addressing/blob/master/src/Subdivision/SubdivisionRepository.php"
    click Country "https://github.com/drafthouse/addressing/tree/master/src/Country/"
    click CountryRepo "https://github.com/drafthouse/addressing/blob/master/src/Country/CountryRepository.php"
    click Zone "https://github.com/drafthouse/addressing/tree/master/src/Zone/"
    click ZoneTerritory "https://github.com/drafthouse/addressing/blob/master/src/Zone/ZoneTerritory.php"
    click DefaultF "https://github.com/drafthouse/addressing/blob/master/src/Formatter/DefaultFormatter.php"
    click PostalF "https://github.com/drafthouse/addressing/blob/master/src/Formatter/PostalLabelFormatter.php"
    click FormatV "https://github.com/drafthouse/addressing/blob/master/src/Validator/Constraints/AddressFormatConstraintValidator.php"
    click CountryV "https://github.com/drafthouse/addressing/blob/master/src/Validator/Constraints/CountryConstraintValidator.php"
    click Constraints "https://github.com/drafthouse/addressing/tree/master/src/Validator/Constraints/"
    click SubdivisionData "https://github.com/drafthouse/addressing/tree/master/resources/subdivision/"
    click JSON "https://github.com/drafthouse/addressing/tree/master/resources/"
```
