# northword/zotero-plugin-scaffold architecture

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

- Interactive diagram: https://gitdiagram.com/northword/zotero-plugin-scaffold
- Repository: https://github.com/northword/zotero-plugin-scaffold

## Overview

##### Main Components
- Monorepo Structure: Represent the overall project as a monorepo containing multiple npm packages.
- Packages: There are three major internal packages:
– “create”: Handles generating scaffolding for new Zotero plugin projects.
– “eslint-config”: Provides standardized ESLint configurations and scripts (including configurations and type generation).
– “scaffold”: This is the core package that contains the CLI, core utilities, and modules for building, testing, releasing, and even starting Zotero in development mode. It includes several submodules:
– CLI entry point (src/cli.ts) to parse commands.
– Core modules:
- Builder (in core/builder.ts)
- Linter (in core/linter.ts)
- Releaser (with submodules like bump management, GitHub integration, Zotero-specific release logic)
- Tester (includes headless testing and HTTP reporting)
- Server component (src/core/server.ts) that may start local services (for plugin testing or live reload)
- Documentation: The “docs” folder (with a VitePress site) shows an external view of how to use these tools.
- CI/CD Pipeline: Represent GitHub workflows (under .github/workflows) that automate testing (ci.yml) and issue management (issuebot.yml).
- Supporting Configuration Tools: Files such as .husky hooks for pre-commit, package.json in the root and in each package, and pnpm workspace configuration files.

##### Relationships and Interactions
- Underlying utility modules – such as utils for file operations, logging, watchers, and integration with Zotero runner – serve the core services. Represent these as shared libraries within the scaffold package.

##### Architectural Patterns & Design Principles
- Modular Design: The project is partitioned into discrete packages, which is ideal for separation of concerns. Each package (create, eslint-config, scaffold) is responsible for its own functionality.
- Layered Services: Within the scaffold, distinguish between core “business logic” (builder, linter, releaser, tester) and “utility services” (file operations, logging, watchers, preference management).
- Testability: Including both unit (in test/unit) and end-to-end tests (test/e2e) emphasizes a design that separates concerns and facilitates testing.

##### Relevant Technologies, Frameworks, and Tools
- TypeScript: Everything is built in TypeScript.
- Node.js & npm (pnpm): The entire ecosystem relies on Node.js with package management (pnpm in a workspace).
- GitHub Actions: For CI/CD automation.
- Husky: For Git hooks.
- VitePress: For documentation hosting.
- ESLint and related tooling: Provided through the eslint-config package.

##### Instructing the Principal Software Engineer
- That each component (package) is clearly labeled.
– Monorepo-level components (packages).
– Internal modules within the scaffold package (command, services, utilities).
– External integrations (GitHub Actions, Zotero client interactions).
- Be very detailed: don’t shy away from splitting the system into many fine-grained components if it means clarity.
- Also, include peripheral elements like the documentation system and CI/CD pipeline to provide a full picture of how the tool is used in development and integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Monorepo Structure"]:::monorepo
    A --> B["Create Package"]:::package
    A --> C["ESLint-Config Package"]:::package
    A --> D["Scaffold Package"]:::package
    A --> E["Documentation (VitePress)"]:::external
    A --> F["CI/CD Pipeline (GitHub Actions)"]:::ci
    A --> G["Git Hooks (Husky)"]:::ci

    subgraph "Scaffold Package Modules"
        D1["CLI Entry Point"]:::module
        D2["Core Builder Module"]:::module
        D3["Core Linter Module"]:::module
        D4["Core Releaser Modules"]:::module
        D5["Core Tester Module"]:::module
        D6["Server Component"]:::module
        D7["Supporting Utility Modules"]:::module
    end

    %% Scaffold Package contains its modules
    D --> D1

    %% CLI triggers core services
    D1 -->|"invokes"| D2
    D1 -->|"invokes"| D3
    D1 -->|"invokes"| D4
    D1 -->|"invokes"| D5
    D1 -->|"invokes"| D6

    %% Core modules use shared utilities
    D2 -->|"uses"| D7
    D3 -->|"uses"| D7
    D4 -->|"uses"| D7
    D5 -->|"uses"| D7
    D6 -->|"uses"| D7

    %% ESLint configuration integration
    C -->|"providesConfigTo"| D3

    %% "Create" bootstraps new projects
    B -->|"bootstraps"| H["Developer/Plugin Project"]:::external

    %% CI/CD Pipeline triggers scaffold actions
    F -->|"triggersBuildLintTest"| D

    %% Styles
    classDef monorepo fill:#fef2cc,stroke:#d8851c,stroke-width:2px;
    classDef package fill:#cce5ff,stroke:#007bff,stroke-width:2px;
    classDef module fill:#e2f0d9,stroke:#31a354,stroke-width:2px;
    classDef external fill:#ffd1dc,stroke:#ff69b4,stroke-width:2px;
    classDef ci fill:#d1d1e0,stroke:#5a5aaf,stroke-width:2px;

    %% Click Events
    click A "https://github.com/northword/zotero-plugin-scaffold/blob/main/pnpm-workspace.yaml"
    click B "https://github.com/northword/zotero-plugin-scaffold/tree/main/packages/create"
    click C "https://github.com/northword/zotero-plugin-scaffold/tree/main/packages/eslint-config"
    click D "https://github.com/northword/zotero-plugin-scaffold/tree/main/packages/scaffold"
    click D1 "https://github.com/northword/zotero-plugin-scaffold/blob/main/packages/scaffold/src/cli.ts"
    click D2 "https://github.com/northword/zotero-plugin-scaffold/blob/main/packages/scaffold/src/core/builder.ts"
    click D3 "https://github.com/northword/zotero-plugin-scaffold/blob/main/packages/scaffold/src/core/linter.ts"
    click D4 "https://github.com/northword/zotero-plugin-scaffold/tree/main/packages/scaffold/src/core/releaser"
    click D5 "https://github.com/northword/zotero-plugin-scaffold/tree/main/packages/scaffold/src/core/tester"
    click D6 "https://github.com/northword/zotero-plugin-scaffold/blob/main/packages/scaffold/src/core/server.ts"
    click D7 "https://github.com/northword/zotero-plugin-scaffold/tree/main/packages/scaffold/src/utils"
    click E "https://github.com/northword/zotero-plugin-scaffold/tree/main/docs"
    click F "https://github.com/northword/zotero-plugin-scaffold/tree/main/.github/workflows"
    click G "https://github.com/northword/zotero-plugin-scaffold/blob/main/.husky"
```
