# apple/password-manager-resources architecture

> Architecture diagram of the GitHub repository apple/password-manager-resources, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apple/password-manager-resources
- Repository: https://github.com/apple/password-manager-resources

## Overview

##### Main Architectural Categories
- Data Resources: The “quirks” directory is the heart of the project. It includes several JSON files (password rules, shared credentials, change-password URLs, Apple appIDs mappings, web extension distribution details, 2FA-related quirks, etc.) and their corresponding JSON schemas.
- Processing Tools: The “tools” directory contains scripts such as the Password Rules Parser (a JavaScript implementation), a JSON autoformatter, a converter for shared credentials, and schema validation scripts. These tools ensure data consistency, parsing, and transformations.
- CI/CD & Developer Automation: The “.github” directory holds GitHub workflows (with Ruby lint scripts and a linting configuration file) that enforce code standards and data integrity.
- Documentation & Governance: Files like README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md and other markdown files form the guidance and process layer of the project, ensuring good collaboration practices.

- Contribution Flow: Optionally include a subsystem for “Developer & Contribution Process” which draws from documentation files (like CONTRIBUTING.md) and indicates how developers push improvements. This reinforces the open-source, collaborative nature of the project.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Clearly separate the static data (quirks) from the processing and validation logic (tools) and from the integration layer (external usage by password managers).
- Data Validation & Consistency: Show that JSON schemas and validation scripts (found in the quirks/schemas and tools folder) ensure reliability and correctness.
- Automation & CI/CD: Emphasize the importance of automated linting and workflows which ensure that every contribution meets quality standards.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Quirks / Data Resources"
        D1["Quirks Data"]:::data
        D2["JSON Schemas"]:::data
    end

    subgraph "Tools & Parsers"
        T1["PasswordRulesParser"]:::tools
        T2["JSON Autoformatter"]:::tools
        T3["SharedCredentialsConverter"]:::tools
        T4["Schema Validator"]:::tools
    end

    subgraph "CI/CD & Workflows"
        C1["CI/CD Root"]:::cicd
        C2["GitHub Workflows"]:::cicd
        C3["LintDuplicates"]:::cicd
        C4["LintSortOrder"]:::cicd
    end

    subgraph "Documentation & Governance"
        Doc1["README.md"]:::doc
        Doc2["CONTRIBUTING.md"]:::doc
        Doc3["CODE_OF_CONDUCT.md"]:::doc
    end

    E1["External Consumers"]:::external

    %% Relationships between components
    D1 -->|"processes"| T1
    D1 -->|"processes"| T2
    D1 -->|"processes"| T3
    D1 -->|"processes"| T4

    C1 --> C2
    C2 -->|"executes"| T4
    C2 -->|"executes"| C3
    C2 -->|"executes"| C4
    C2 -->|"validates"| D2

    D1 -->|"provides"| E1

    Doc2 -->|"contributes"| D1

    %% Click Events for Data Resources
    click D1 "https://github.com/apple/password-manager-resources/tree/main/quirks"
    click D2 "https://github.com/apple/password-manager-resources/tree/main/quirks/schemas"

    %% Click Events for Processing Tools
    click T1 "https://github.com/apple/password-manager-resources/blob/main/tools/PasswordRulesParser.js"
    click T2 "https://github.com/apple/password-manager-resources/blob/main/tools/autoformat-json-files.rb"
    click T3 "https://github.com/apple/password-manager-resources/blob/main/tools/convert-shared-credential-to-legacy-format.rb"
    click T4 "https://github.com/apple/password-manager-resources/blob/main/tools/validate-json-schemas.sh"

    %% Click Events for CI/CD & Developer Automation
    click C1 "https://github.com/apple/password-manager-resources/blob/main/.github"
    click C2 "https://github.com/apple/password-manager-resources/tree/main/.github/workflows"
    click C3 "https://github.com/apple/password-manager-resources/blob/main/.github/workflows/lint-scripts/websites-shared-credentials-duplicates.rb"
    click C4 "https://github.com/apple/password-manager-resources/blob/main/.github/workflows/lint-scripts/websites-shared-credentials-sort-order.rb"

    %% Click Events for Documentation & Governance
    click Doc1 "https://github.com/apple/password-manager-resources/blob/main/README.md"
    click Doc2 "https://github.com/apple/password-manager-resources/blob/main/CONTRIBUTING.md"
    click Doc3 "https://github.com/apple/password-manager-resources/blob/main/CODE_OF_CONDUCT.md"

    %% Styles
    classDef data fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef tools fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef cicd fill:#577590,stroke:#333,stroke-width:2px,color:#fff;
    classDef doc fill:#f9844a,stroke:#333,stroke-width:2px;
    classDef external fill:#f94144,stroke:#333,stroke-width:2px,color:#fff;
```
