# nypl/metadata-documentation architecture

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

- Interactive diagram: https://gitdiagram.com/nypl/metadata-documentation
- Repository: https://github.com/nypl/metadata-documentation

## Overview

This project is a documentation website built to house and present best practices, workflows, guidelines, and reference materials for NYPL’s Metadata Services Unit. From the file tree and the README, we can deduce that the site is statically generated (likely using Jekyll, given the presence of a Gemfile, _config.yml, and Markdown content files) and is organized into several thematic sections (e.g., metadata, workflows, system, projects, colophon, etc.).

##### Project’s Main Components
- Static Site Generator: Represent the tool (likely Jekyll) that reads configuration (_config.yml), uses Gemfile-managed dependencies, processes Markdown (.md) files, and builds the final static site.
- Content Sections: Group content by thematic areas visible in the file tree:
- Metadata: Contains guidelines, definitions and standardized content for metadata (the “metadata” folder with subdirectories like “element”, “material”, etc.).
- Workflows: Contains documentation on digitization, importing, remediation, rights, etc.
- System: Documentation on internal systems like accounts, training, and overall system operations.
- Projects, Colophon, DC (document control), and Contact: Other sections of the documentation site.
- Shared Components & Assets: Including the _includes (for reusable HTML snippets like head and footer navigation), the assets folder (images, JavaScript), and configuration templates.
- External Repositories: The README mentions related internal repos (metadata-admin, metadata-projects, metadata-tools) that could be noted as external resources or integrations.

##### Relationships and Interactions
- The Static Site Generator (Jekyll) takes input from the Markdown files, the _includes folder, and the assets folder. It then processes these inputs guided by _config.yml and Gemfile, resulting in the final rendered website.
- The content directories are “plugged into” the site’s structure—each with specific purposes (for example, workflows detail operational procedures while metadata focuses on technical elements).
- There is a logical navigation flow between the sections (e.g., the navigation and footer included in _includes provide links to all major sections).
- External links (mentioned in the README) highlight the relationship between public documentation and internal repositories.

##### Architectural Patterns & Design Principles
- Static Site Generation: Emphasize that the architecture relies on pre-building content from Markdown into HTML.
- Separation of Concerns: The project clearly distinguishes between content (Markdown files organized by topic), presentation (custom HTML snippets in _includes and assets), and configuration (via _config.yml and Gemfile).
- Modularity and Extensibility: Multiple directories and subdirectories indicate the project is organized into modular topics that can be independently maintained and expanded.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build/Processing Layer
    subgraph "Build/Processing Layer"
        subgraph "Inputs"
            subgraph "Configuration Files"
                ConfigYml["_config.yml"]:::config
                Gemfile["Gemfile"]:::config
                GemfileLock["Gemfile.lock"]:::config
            end
            subgraph "Content Sections"
                Metadata["Metadata Content"]:::content
                Workflows["Workflows Documentation"]:::content
                SystemDoc["System Documentation"]:::content
                Projects["Projects Documentation"]:::content
                Colophon["Colophon Content"]:::content
                DC["Document Control (DC)"]:::content
                Contact["Contact Section"]:::content
            end
            subgraph "Shared Components"
                Includes["Shared Includes"]:::shared
                Assets["Shared Assets"]:::shared
            end
        end
        SiteGen["Jekyll Builder"]:::builder
        ConfigYml --> SiteGen
        Gemfile --> SiteGen
        GemfileLock --> SiteGen
        Metadata --> SiteGen
        Workflows --> SiteGen
        SystemDoc --> SiteGen
        Projects --> SiteGen
        Colophon --> SiteGen
        DC --> SiteGen
        Contact --> SiteGen
        Includes --> SiteGen
        Assets --> SiteGen
        SiteGen --> StaticOut["Static Website Output"]:::output
    end

    %% External Repositories Reference (Integration)
    External["External Repositories Reference"]:::external
    External --- SiteGen

    %% Click Events Configuration Files
    click ConfigYml "https://github.com/nypl/metadata-documentation/blob/main/_config.yml"
    click Gemfile "https://github.com/nypl/metadata-documentation/tree/main/Gemfile"
    click GemfileLock "https://github.com/nypl/metadata-documentation/blob/main/Gemfile.lock"

    %% Click Events Content Sections
    click Metadata "https://github.com/nypl/metadata-documentation/tree/main/metadata/"
    click Workflows "https://github.com/nypl/metadata-documentation/tree/main/workflows/"
    click SystemDoc "https://github.com/nypl/metadata-documentation/tree/main/system/"
    click Projects "https://github.com/nypl/metadata-documentation/tree/main/projects/"
    click Colophon "https://github.com/nypl/metadata-documentation/tree/main/colophon/"
    click DC "https://github.com/nypl/metadata-documentation/tree/main/dc/"
    click Contact "https://github.com/nypl/metadata-documentation/tree/main/contact/"

    %% Click Events Shared Components
    click Includes "https://github.com/nypl/metadata-documentation/tree/main/_includes/"
    click Assets "https://github.com/nypl/metadata-documentation/tree/main/assets/"

    %% Click Event for External Repositories Reference
    click External "https://github.com/nypl/metadata-documentation/blob/main/README.md"

    %% Styles
    classDef config fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef content fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef shared fill:#ccccff,stroke:#0000cc,stroke-width:2px;
    classDef builder fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef output fill:#ffccff,stroke:#cc0099,stroke-width:2px;
    classDef external fill:#ccffff,stroke:#009999,stroke-width:2px;
```
