# johnsundell/publish architecture

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

- Interactive diagram: https://gitdiagram.com/johnsundell/publish
- Repository: https://github.com/johnsundell/publish

## Overview

##### Project type and purpose
- This is a Swift-based static site generator library and command-line tool (“Publish”), used to build entire websites as Swift packages.
- It provides a core library (API + internal modules) and a CLI (PublishCLI) with associated core logic (PublishCLICore).
- It supports themes (using Plot), plugins, custom publishing pipelines, deployment methods, and local HTTP serving.

##### File structure
- Top-level:
- Package.swift, Makefile, README, LICENSE, .gitignore
- Documentation folder (how-to guides and reference docs)
- Resources folder (foundation theme CSS)
- Sources folder, subdivided into:
­ Publish (split into API and Internal)
­ PublishCLI (entry point main.swift)
­ PublishCLICore (core CLI command logic, project/website generation, runner, deployer)
- Tests folder (PublishTests with Infrastructure helpers + unit tests)
- This indicates a layered, modular architecture:
­ Presentation/entry: CLI modules
­ Core library: API + internal implementations
­ External-facing resources and docs
­ Testing infrastructure
- Configuration files: Swift Package manifest (Package.swift), Makefile for building the CLI.

##### Key insights from README
- Core abstractions: Website, Section, Item, Page, PublishingStep, PublishingContext, Plugin, Theme/HTMLFactory.
- Pipeline pattern: series of steps (addMarkdownFiles, copyResources, generateHTML, generateRSSFeed, generateSiteMap, deploy).
- Factory pattern: HTMLFactory to produce HTML via Plot.
- Plugin architecture: extensions that modify PublishingContext.
- DeploymentMethod abstraction with built-in Git/GitHub deployments.
- Local HTTP server for “publish run”.

##### Main components
a. User & Configuration
­ – Website Swift package (Package.swift + Content folder + custom code)
­ – Custom themes/plugins/publishing steps
b. CLI Layer
­ – PublishCLI (main.swift) – entry point, parses command-line arguments
­ – PublishCLICore – orchestrates commands: new, publish, run, deploy
c. Core Library Layer (Publish)
­ – API module (public types: Website, Section, Item, Page, PublishingStep, Theme, Plugin, DeploymentMethod)
­ – Internal module (Markdown parsing, file I/O, pipeline engine, HTMLGenerator, RSS/PodcastFeedGenerator, SiteMapGenerator)
d. External Dependencies
­ – Plot (HTML DSL)
­ – Splash (syntax highlighting plugin example)
­ – Swift Package Manager (packaging/build)
­ – Git/GitHub (deployment)
e. Output & Side-Effects
­ – File system (generated HTML/CSS/JS/assets, RSS, sitemap)
­ – Local HTTP server (for “run” command)
­ – Remote server / GitHub Pages (on deploy)

##### Relationships and interactions
- User invokes `publish` or runs Xcode-built executable → PublishCLI
- PublishCLI delegates to PublishCLICore → selects the appropriate command handler
- PublishCLICore calls into Publish API:
- For “new”: ProjectGenerator creates a website template
- For “publish”: WebsiteGenerator triggers `Website.publish(...)`
- For “run”: WebsiteRunner spins up HTTP server and monitors changes
- For “deploy”: WebsiteDeployer invokes DeploymentMethod
- `Website.publish` builds a PublishingPipeline:
- A sequence of PublishingStep instances
- Each step receives a PublishingContext and mutates it
- Internal modules handle Markdown parsing, HTML generation (HTMLGenerator → uses HTMLFactory), feed generation, site map, resource copying
- At the end of the pipeline, files are written to disk
- Deploy step (if enabled) pushes output via Git or GitHub API
- Plugins (extensions of Plugin) and themes (HTMLFactory implementations) hook into pipeline

##### Architectural patterns & design principles
- Layered architecture: CLI → core-logic → API → internal implementation
- Pipeline pattern for content generation
- Factory pattern for HTML generation (HTMLFactory)
- Plugin/extensible design: both publishing steps and plugins extend PublishingContext
- Strong modular separation: core library is framework-agnostic; CLI builds on it
- Type safety: all website configuration expressed in Swift types

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-provided code
    subgraph "User Website Package" 
        direction TB
        UserPkg["Website Swift Package"]:::user
        CustomExt["Custom Themes & Plugins"]:::user
    end

    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        PublishCLI["PublishCLI"]:::cli
        subgraph "PublishCLICore"
            direction TB
            PG["ProjectGenerator"]:::cli
            WG["WebsiteGenerator"]:::cli
            WR["WebsiteRunner"]:::cli
            WDl["WebsiteDeployer"]:::cli
        end
    end

    %% Core Library
    subgraph "Publish Core Library"
        direction TB
        subgraph "API Module"
            direction TB
            API["Publish API"]:::core
        end
        subgraph "Internal Module"
            direction TB
            Internal["Publish Internal"]:::core
        end
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        Plot["Plot (HTML DSL)"]:::external
        SPM["SwiftPM"]:::external
        Git["Git/GitHub"]:::external
    end

    %% Outputs & Side Effects
    subgraph "Outputs & Side Effects"
        direction TB
        FS["File System"]:::output
        HTTP["Local HTTP Server"]:::output
        RS["Remote Server"]:::output
    end

    %% Relationships
    UserPkg -->|"run command"| PublishCLI
    CustomExt -->|"plugins/themes"| API

    PublishCLI -->|"delegate"| PG
    PublishCLI -->|"delegate"| WG
    PublishCLI -->|"delegate"| WR
    PublishCLI -->|"delegate"| WDl

    PG -->|"scaffold site"| FS

    WG -->|"publish() call"| API
    WR -->|"run server"| Internal
    WDl -->|"deploy() call"| API

    API -->|"build pipeline"| Internal
    Internal -->|"generate files"| FS

    FS -->|"serve content"| HTTP
    FS -->|"push content"| Git
    Git -->|"host site"| RS

    %% External integrations
    Internal -->|uses| Plot
    PG -->|uses| SPM
    WDl -->|uses| Git

    %% Click Events
    click PublishCLI "https://github.com/johnsundell/publish/blob/master/Sources/PublishCLI/main.swift"
    click PG "https://github.com/johnsundell/publish/blob/master/Sources/PublishCLICore/ProjectGenerator.swift"
    click WG "https://github.com/johnsundell/publish/blob/master/Sources/PublishCLICore/WebsiteGenerator.swift"
    click WR "https://github.com/johnsundell/publish/blob/master/Sources/PublishCLICore/WebsiteRunner.swift"
    click WDl "https://github.com/johnsundell/publish/blob/master/Sources/PublishCLICore/WebsiteDeployer.swift"
    click API "https://github.com/johnsundell/publish/tree/master/Sources/Publish/API"
    click Internal "https://github.com/johnsundell/publish/tree/master/Sources/Publish/Internal"

    %% Styles
    classDef user fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef cli fill:#add8e6,stroke:#333,stroke-width:1px
    classDef core fill:#ffa500,stroke:#333,stroke-width:1px
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
    classDef output fill:#ffeb3b,stroke:#333,stroke-width:1px
```
