# yalesites-org/yalesites-project architecture

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

- Interactive diagram: https://gitdiagram.com/yalesites-org/yalesites-project
- Repository: https://github.com/yalesites-org/yalesites-project

## Overview

This project is a full‐stack platform built to serve as a custom Drupal upstream on Pantheon – essentially a tailored digital experience framework for the Yale community. It is designed as both the codebase and the configuration repository that supports local development, automated code quality and testing processes, and continuous integration and delivery to production on Pantheon.

##### And Label Key Components

- Local Development Environment:
- Local developer “sandbox” that uses tools such as Lando (with example .lando files), npm build scripts (as seen in package.json and scripts/local/), and Composer for PHP dependencies.
- Blocks for the various npm scripts (build, build-with-assets, build-with-install, confex/confim, local:theme-link, etc.) which streamline local site builds and configuration synchronization.

- Continuous Integration / Delivery (CI/CD) Pipeline:

- Pantheon and Deployment Infrastructure:
- Components for Pantheon configurations (pantheon.yml, pantheon.upstream.yml, and specific deployment subdirectories under .ci/deploy for Pantheon) that drive how the built site is deployed to the Pantheon environment.

- Drupal Code, Configuration, and Custom Modules/Themes:
- “web” directory as the heart of the Drupal installation, including custom sites, profiles (especially “yalesites_profile” which underpins the platform’s custom modules, themes, and configurations), and contributed modules.

- External Dependencies and Configuration Files:
- General configuration files (composer.json, package.json, etc.) as an “External Libraries & Dependencies” block.
- Documentation and configuration directories (docs, config, patches) that support the overall maintenance and integration of the platform.

##### Relationships and Interactions

- Code Flow:

- CI/CD Process:
- That commits trigger GitHub workflows that run tests, export/import configurations (confex/confim), and run build scripts.
- From the CI pipelines, illustrate the process to package and deliver builds to the deployment system.

- Deployment Pipeline:
- That once the CI/CD checks pass, the built code and configuration are then deployed to Pantheon via automated scripts (e.g., those under .ci/deploy and GitHub deployment workflows).

- Separation of Concerns:
- Separation between frontend (theme development and asset building) and backend (Drupal, custom modules, configuration management) which are supported by dedicated scripts and configuration management practices.

##### Architectural Patterns and Design Principles

- Modular Architecture:
- Significance of modularity – Drupal itself is modular, and the project leverages this by having separate custom modules and themes. Visually separate these modules and clearly label which areas are customizations for YaleSites.

- Automation and Continuous Delivery:
- Deep integration of CI/CD, with automated testing, code quality checks, and build processes. Represent these as a distinct pipeline driving both the build-time and deployment-time activities.

- Environment Parity:

- Versioning and Configuration Management:

##### Putting It All Together

- Finally, connect the finalized build to a “Deployment” block that represents Pantheon (including the upstream configuration) and ultimately to the running “Drupal Application” environment, where Drupal code, custom modules and themes are executed.
- Optionally, include a side section that summarizes external dependencies (like Composer and npm packages) feeding into the Drupal code base.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Repository
    Repo["Source Repository (GitHub)"]:::repository

    %% Local Development Environment Subgraph
    subgraph "Local Development Environment"
        Lando_LocalConfig["Local Dev: Lando Config"]:::dev
        Lando_UpstreamConfig["Local Dev: Lando Upstream Config"]:::dev
        Npm_Package["Local Dev: npm Package"]:::dev
        Local_Scripts["Local Dev: Local Scripts"]:::dev
    end

    %% CI/CD Pipeline Subgraph
    subgraph "CI/CD Pipeline"
        CI_Config["CI/CD: .ci Directory"]:::cicd
        GitHub_Workflows["CI/CD: GitHub Workflows"]:::cicd
        Husky_Hooks["CI/CD: Husky Hooks"]:::cicd
    end

    %% Build & Test Stage
    BuildAndTest["Build & Test (Automation)"]:::build

    %% Pantheon Deployment Subgraph
    subgraph "Pantheon Deployment"
        Pantheon_Config["Pantheon: Config (pantheon.yml)"]:::deployment
        Pantheon_Upstream["Pantheon: Upstream Config (pantheon.upstream.yml)"]:::deployment
        Pantheon_Deploy["Pantheon: Deploy Scripts"]:::deployment
        Pantheon_Dev["Pantheon: Dev (Multidev)"]:::deployment
    end

    %% Drupal Application Subgraph
    subgraph "Drupal Application"
        Drupal_Codebase["Drupal: Codebase (/web)"]:::drupal
        Drupal_Custom_Profile["Drupal: Custom Profile & Modules"]:::drupal
        Drupal_Custom_Themes["Drupal: Custom Themes"]:::drupal
        Drupal_SiteSettings["Drupal: Site Settings"]:::drupal
    end

    %% External Dependencies Subgraph
    subgraph "External Dependencies"
        Composer_File["Composer & Dependencies"]:::external
        Config_Files["Config Files"]:::external
        Patches["Patches"]:::external
        Documentation["Documentation"]:::external
    end

    %% Connections
    Repo -->|"commits"| Npm_Package
    Repo -->|"commits"| CI_Config

    %% Local Dev internal flow
    Lando_LocalConfig --> Lando_UpstreamConfig
    Lando_UpstreamConfig --> Npm_Package
    Npm_Package --> Local_Scripts

    %% CI/CD internal flow
    CI_Config --> GitHub_Workflows
    GitHub_Workflows --> Husky_Hooks

    %% Link between Local Dev and CI/CD
    Local_Scripts --> Husky_Hooks

    %% CI/CD to Build & Test
    Husky_Hooks --> BuildAndTest

    %% Build & Test to Pantheon Deployment
    BuildAndTest --> Pantheon_Config
    Pantheon_Config --> Pantheon_Upstream
    Pantheon_Upstream --> Pantheon_Deploy
    Pantheon_Deploy --> Pantheon_Dev

    %% Deployment to Drupal Application
    Pantheon_Dev --> Drupal_Codebase
    Drupal_Codebase --> Drupal_Custom_Profile
    Drupal_Custom_Profile --> Drupal_Custom_Themes
    Drupal_Custom_Themes --> Drupal_SiteSettings

    %% External Dependencies feeding into Drupal Application
    Composer_File --- Drupal_Codebase
    Config_Files --- Drupal_Codebase
    Patches --- Drupal_Codebase
    Documentation --- Drupal_Codebase

    %% Click Events for Local Development Environment
    click Lando_LocalConfig "https://github.com/yalesites-org/yalesites-project/blob/develop//.lando.local.example.yml"
    click Lando_UpstreamConfig "https://github.com/yalesites-org/yalesites-project/blob/develop//.lando.upstream.yml"
    click Npm_Package "https://github.com/yalesites-org/yalesites-project/blob/develop//package.json"
    click Local_Scripts "https://github.com/yalesites-org/yalesites-project/tree/develop//scripts/local/"

    %% Click Events for CI/CD Pipeline
    click CI_Config "https://github.com/yalesites-org/yalesites-project/blob/develop//.ci"
    click GitHub_Workflows "https://github.com/yalesites-org/yalesites-project/tree/develop//.github/workflows"
    click Husky_Hooks "https://github.com/yalesites-org/yalesites-project/tree/develop//.husky/"

    %% Click Events for Pantheon and Deployment Infrastructure
    click Pantheon_Config "https://github.com/yalesites-org/yalesites-project/blob/develop//pantheon.yml"
    click Pantheon_Upstream "https://github.com/yalesites-org/yalesites-project/blob/develop//pantheon.upstream.yml"
    click Pantheon_Deploy "https://github.com/yalesites-org/yalesites-project/tree/develop//.ci/deploy/pantheon"
    click Pantheon_Dev "https://github.com/yalesites-org/yalesites-project/tree/develop//.ci/deploy/pantheon/dev-multidev"

    %% Click Events for Drupal Code, Configuration, and Custom Modules/Themes
    click Drupal_Codebase "https://github.com/yalesites-org/yalesites-project/tree/develop//web"
    click Drupal_Custom_Profile "https://github.com/yalesites-org/yalesites-project/tree/develop//web/profiles/custom/yalesites_profile"
    click Drupal_Custom_Themes "https://github.com/yalesites-org/yalesites-project/tree/develop//web/themes/custom/ys_admin_theme"
    click Drupal_SiteSettings "https://github.com/yalesites-org/yalesites-project/tree/develop//web/sites"

    %% Click Events for External Dependencies and Configuration Files
    click Composer_File "https://github.com/yalesites-org/yalesites-project/blob/develop/composer.json"
    click Config_Files "https://github.com/yalesites-org/yalesites-project/tree/develop//config"
    click Patches "https://github.com/yalesites-org/yalesites-project/tree/develop//patches"
    click Documentation "https://github.com/yalesites-org/yalesites-project/tree/develop//docs"

    %% Styles
    classDef repository fill:#a7c7e7,stroke:#000,stroke-width:2px,color:#000;
    classDef dev fill:#cfeecc,stroke:#000,stroke-width:2px,color:#000;
    classDef cicd fill:#fff2ae,stroke:#000,stroke-width:2px,color:#000;
    classDef build fill:#d3bdf0,stroke:#000,stroke-width:2px,color:#000;
    classDef deployment fill:#b0e0e6,stroke:#000,stroke-width:2px,color:#000;
    classDef drupal fill:#ffcccc,stroke:#000,stroke-width:2px,color:#000;
    classDef external fill:#fce5cd,stroke:#000,stroke-width:2px,color:#000;
```
