# laladim/newsletter-icm-workbook architecture

> Architecture diagram of the GitHub repository laladim/newsletter-icm-workbook, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/laladim/newsletter-icm-workbook
- Repository: https://github.com/laladim/newsletter-icm-workbook

## Overview

Newsletter ICM Workbook is a file-based guided workflow for designing and operating a newsletter with human approval gates and a local-first edition process. A person or small team uses the discovery material, optionally with a coding agent, to approve a brief and publication profile, then creates and works through a nine-stage edition. The README documents research, editorial, visual, delivery, and learning capabilities; the stage templates define their handoffs. Sampled scripts show stamping and verification, but most stage execution is documented as a human/agent workflow rather than application code.

Main entry points: [`scripts/stamp.py`](https://github.com/laladim/newsletter-icm-workbook/blob/main/scripts/stamp.py) (Workspace stamper), [`_templates/publication/publication-brief.md`](https://github.com/laladim/newsletter-icm-workbook/blob/main/_templates/publication/publication-brief.md) (Publication brief), [`publications`](https://github.com/laladim/newsletter-icm-workbook/tree/main/publications) (Approved publication), [`editions`](https://github.com/laladim/newsletter-icm-workbook/tree/main/editions) (Edition records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Discovery and profile"]
  node_discovery_guide["Discovery workbook"]
  node_setup["Workspace setup<br/>[SETUP.md]"]
  node_brief_template["Publication brief"]
  node_publication_profile["Publication contracts"]
  node_publication["Approved publication"]
end

subgraph group_edition["Edition workflow"]
  node_intake["Intake"]
  node_source_selection["Source selection"]
  node_research["Research and verification"]
  node_routing["Editorial routing"]
  node_draft["Newsletter draft"]
  node_quality["Quality and risk review"]
  node_package["Visuals and packaging"]
  node_delivery["Delivery and preview"]
  node_post_publish["Post-publish learning"]
  node_editions["Edition records"]
end

subgraph group_controls["Generation and checks"]
  node_stamp["Workspace stamper<br/>[stamp.py]"]
  node_publication_check["Profile verifier"]
  node_edition_check["Edition verifier<br/>[verify-edition.py]"]
end

subgraph group_example["Sanitized example"]
  node_case_study["Beyond Banks example"]
end

node_person(("Publisher / team"))
node_agent(("Coding agent"))
node_platform["Publishing platform"]

node_person -->|"answers prompts"| node_discovery_guide
node_person -->|"starts workspace"| node_setup
node_agent -->|"guides interview"| node_discovery_guide
node_agent -->|"drafts brief"| node_brief_template
node_person -->|"approves brief"| node_brief_template
node_brief_template -->|"provides brief"| node_stamp
node_stamp -->|"renders contracts"| node_publication_profile
node_stamp -->|"runs verification"| node_publication_check
node_publication_check -->|"checks profile"| node_publication
node_person -->|"approves profile"| node_publication
node_publication -->|"authorizes edition"| node_stamp
node_stamp -->|"stamps stages"| node_intake
node_intake -->|"hands off"| node_source_selection
node_source_selection -->|"hands off"| node_research
node_research -->|"hands off"| node_routing
node_routing -->|"hands off"| node_draft
node_draft -->|"hands off"| node_quality
node_quality -->|"hands off"| node_package
node_package -->|"hands off"| node_delivery
node_delivery -->|"hands off"| node_post_publish
node_post_publish -->|"records learning"| node_editions
node_edition_check -->|"checks receipts"| node_editions
node_editions -->|"presents local output"| node_person
node_person -.->|"may authorize pilot"| node_platform
node_case_study -->|"illustrates transformation"| node_person

click node_discovery_guide "https://github.com/laladim/newsletter-icm-workbook/blob/main/NEW-NEWSLETTER-DISCOVERY.md"
click node_setup "https://github.com/laladim/newsletter-icm-workbook/blob/main/SETUP.md"
click node_brief_template "https://github.com/laladim/newsletter-icm-workbook/blob/main/_templates/publication/publication-brief.md"
click node_publication_profile "https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/publication"
click node_publication "https://github.com/laladim/newsletter-icm-workbook/tree/main/publications"
click node_intake "https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/01_intake"
click node_source_selection "https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/02_source-selection"
click node_research "https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/03_research"
click node_routing "https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/04_routing"
click node_draft "https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/05_draft"
click node_quality "https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/06_quality-review"
click node_package "https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/07_package"
click node_delivery "https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/08_delivery"
click node_post_publish "https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/09_post-publish"
click node_editions "https://github.com/laladim/newsletter-icm-workbook/tree/main/editions"
click node_stamp "https://github.com/laladim/newsletter-icm-workbook/blob/main/scripts/stamp.py"
click node_publication_check "https://github.com/laladim/newsletter-icm-workbook/blob/main/scripts/verify-publication.py"
click node_edition_check "https://github.com/laladim/newsletter-icm-workbook/blob/main/scripts/verify-edition.py"
click node_case_study "https://github.com/laladim/newsletter-icm-workbook/tree/main/examples/beyond-banks"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_discovery_guide,node_setup,node_brief_template,node_publication_profile,node_publication toneBlue
class node_intake,node_source_selection,node_research,node_routing,node_draft,node_quality,node_package,node_delivery,node_post_publish,node_editions toneAmber
class node_stamp,node_publication_check,node_edition_check toneMint
class node_case_study toneRose
class node_person,node_agent,node_platform toneIndigo
```

## Components

### Discovery and profile

- [Discovery workbook](https://github.com/laladim/newsletter-icm-workbook/blob/main/NEW-NEWSLETTER-DISCOVERY.md): `NEW-NEWSLETTER-DISCOVERY.md`
- [Workspace setup](https://github.com/laladim/newsletter-icm-workbook/blob/main/SETUP.md): `SETUP.md`
- [Publication brief](https://github.com/laladim/newsletter-icm-workbook/blob/main/_templates/publication/publication-brief.md): `_templates/publication/publication-brief.md`
- [Publication contracts](https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/publication): `_templates/publication`
- [Approved publication](https://github.com/laladim/newsletter-icm-workbook/tree/main/publications): `publications`

### Edition workflow

- [Intake](https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/01_intake): `_templates/edition/01_intake`
- [Source selection](https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/02_source-selection): `_templates/edition/02_source-selection`
- [Research and verification](https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/03_research): `_templates/edition/03_research`
- [Editorial routing](https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/04_routing): `_templates/edition/04_routing`
- [Newsletter draft](https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/05_draft): `_templates/edition/05_draft`
- [Quality and risk review](https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/06_quality-review): `_templates/edition/06_quality-review`
- [Visuals and packaging](https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/07_package): `_templates/edition/07_package`
- [Delivery and preview](https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/08_delivery): `_templates/edition/08_delivery`
- [Post-publish learning](https://github.com/laladim/newsletter-icm-workbook/tree/main/_templates/edition/09_post-publish): `_templates/edition/09_post-publish`
- [Edition records](https://github.com/laladim/newsletter-icm-workbook/tree/main/editions): `editions`

### Generation and checks

- [Workspace stamper](https://github.com/laladim/newsletter-icm-workbook/blob/main/scripts/stamp.py): `scripts/stamp.py`
- [Profile verifier](https://github.com/laladim/newsletter-icm-workbook/blob/main/scripts/verify-publication.py): `scripts/verify-publication.py`
- [Edition verifier](https://github.com/laladim/newsletter-icm-workbook/blob/main/scripts/verify-edition.py): `scripts/verify-edition.py`

### Sanitized example

- [Beyond Banks example](https://github.com/laladim/newsletter-icm-workbook/tree/main/examples/beyond-banks): `examples/beyond-banks`

### Other components

- **Publisher / team**
- **Coding agent**
- **Publishing platform**

## Connections

- Publisher / team → Discovery workbook: answers prompts
- Publisher / team → Workspace setup: starts workspace
- Coding agent → Discovery workbook: guides interview
- Coding agent → Publication brief: drafts brief
- Publisher / team → Publication brief: approves brief
- Publication brief → Workspace stamper: provides brief
- Workspace stamper → Publication contracts: renders contracts
- Workspace stamper → Profile verifier: runs verification
- Profile verifier → Approved publication: checks profile
- Publisher / team → Approved publication: approves profile
- Approved publication → Workspace stamper: authorizes edition
- Workspace stamper → Intake: stamps stages
- Intake → Source selection: hands off
- Source selection → Research and verification: hands off
- Research and verification → Editorial routing: hands off
- Editorial routing → Newsletter draft: hands off
- Newsletter draft → Quality and risk review: hands off
- Quality and risk review → Visuals and packaging: hands off
- Visuals and packaging → Delivery and preview: hands off
- Delivery and preview → Post-publish learning: hands off
- Post-publish learning → Edition records: records learning
- Edition verifier → Edition records: checks receipts
- Edition records → Publisher / team: presents local output
- Publisher / team → Publishing platform: may authorize pilot
- Beyond Banks example → Publisher / team: illustrates transformation