# zarazhangrui/follow-builders architecture

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

- Interactive diagram: https://gitdiagram.com/zarazhangrui/follow-builders
- Repository: https://github.com/zarazhangrui/follow-builders

## Overview

This repository is a packaged “skill” for an AI agent, centered around a centrally maintained content feed and a local digest-generation/delivery workflow.

#### High-level architecture

The repo has three main layers:

1. **Skill / prompt layer**
   - Defines how an agent should behave when a user asks to set up or modify the “Follow Builders” digest.
   - Lives mostly in `SKILL.md` and the `prompts/` folder.
   - This layer does not fetch content itself; it shapes summarization, translation, and digest tone.

2. **Central feed production layer**
   - A GitHub Actions workflow updates the canonical feed on a schedule.
   - Lives in `.github/workflows/generate-feed.yml` and the feed/source JSON files.
   - This is the shared upstream data source for all users, which is why the skill does not require user API keys.

3. **Local digest orchestration layer**
   - User-side scripts prepare the digest and optionally deliver it to a destination.
   - Lives in `scripts/` and is backed by local config/state.
   - This is where user preferences, language choice, and delivery settings are applied.

#### Main subsystems

##### 1) Source registry and content model
The repo distinguishes between curated source lists and generated feed artifacts:

- `config/default-sources.json` appears to define the canonical source set used by the skill.
- `feed-blogs.json`, `feed-podcasts.json`, and `feed-x.json` represent source-specific feed inputs or cached feed definitions for:
  - official AI blogs,
  - podcast channels,
  - X/Twitter accounts.

This is the boundary between “what to follow” and “how to summarize it.”

##### 2) Feed generation pipeline
The central feed is updated by a scheduled automation:

- `.github/workflows/generate-feed.yml` is the orchestration entrypoint.
- `scripts/generate-feed.js` is the main generator script.
- `state-feed.json` likely stores the last processed state, deduplication markers, or incremental generation metadata.

The README says the central feed is built from:
- blog articles via scraping,
- YouTube transcripts via Supadata,
- X/Twitter via the official API.

That means the feed-generation boundary depends on external content platforms, but those integrations are centralized so end users don’t manage credentials.

##### 3) Digest preparation
Once the feed exists, the local skill turns it into a user-specific digest:

- `scripts/prepare-digest.js` likely selects new items from the feed, applies language preferences, and assembles a digest structure.
- `prompts/digest-intro.md` defines the top-level framing, tone, and layout of the digest.
- `prompts/summarize-podcast.md`, `prompts/summarize-tweets.md`, and `prompts/summarize-blogs.md` define content-type-specific summarization behavior.
- `prompts/translate.md` handles translation into Chinese or bilingual output.

This layer is where raw content becomes readable, concise summaries.

##### 4) Delivery
Delivery is separated from preparation:

- `scripts/deliver.js` likely pushes the finished digest to an endpoint or messaging channel.
- The README mentions Telegram, email, Discord, WhatsApp, or in-chat delivery.
- Delivery credentials are local-only, stored in `~/.follow-builders/.env`.

This is an important architectural boundary: content fetching is centralized, but delivery secrets remain on the user’s machine.

##### 5) Configuration and validation
The repo includes configuration structure rather than hard-coded behavior:

- `config/config-schema.json` suggests user settings are validated against a schema.
- The README indicates the agent configures:
  - frequency,
  - time,
  - language,
  - delivery destination,
  - summary style/verbosity.

This is the personalization layer, and it sits above the shared source registry and feed.

##### 6) Examples and documentation
- `examples/sample-digest.md` shows the expected output shape.
- `README.md` and `README.zh-CN.md` explain the workflow and user-facing philosophy.
- `SKILL.md` is likely the agent-facing operational description.

These files are not runtime dependencies, but they define the contract the agent should follow.

#### Key data flows

##### A. Central content ingestion flow
1. Public content is pulled from curated sources.
2. The scheduled GitHub Action runs `scripts/generate-feed.js`.
3. Generated feed artifacts are written/updated, with `state-feed.json` helping maintain continuity.
4. The resulting feed becomes the shared upstream source for all users.

##### B. Local digest generation flow
1. The agent reads the central feed.
2. User preferences and delivery settings are applied.
3. Type-specific prompts summarize blogs, podcasts, and X posts.
4. Translation or bilingual formatting is applied if requested.
5. `scripts/prepare-digest.js` produces the final digest content.

##### C. Delivery flow
1. The prepared digest is handed to `scripts/deliver.js`.
2. A local delivery integration sends it to the configured target.
3. Secrets stay local; only public content is fetched centrally.

#### Architectural boundaries worth showing in a diagram

##### Central vs local
This is the most important boundary in the repo:

- **Central, shared, automated:** source fetching, feed generation, update cadence.
- **Local, user-specific:** preferences, prompt customization, delivery credentials, final dispatch.

##### Source retrieval vs summarization
Another clear boundary:

- Raw public content is ingested once into the feed.
- The digest is generated later, per user, with their preferred tone, length, and language.

##### Content types
The system treats three content families differently:
- podcasts,
- X/Twitter posts,
- official blogs.

Each has its own prompt and likely its own extraction/summarization path.

#### Technologies and operational characteristics

- **Node.js** is the scripting/runtime layer, based on `scripts/package.json` and `scripts/package-lock.json`.
- **GitHub Actions** is used for scheduled feed generation.
- **Markdown prompt files** are used as editable behavior specs for the agent.
- **JSON** is used for source lists, schema, and state.

#### What this repository is not

It is not a traditional web app or a single monolithic backend. It is closer to:
- a curated content pipeline,
- an agent skill package,
- and a delivery/orchestration toolkit.

The architectural center of gravity is the separation between:
- centrally maintained content aggregation,
- and local, preference-driven digest assembly and delivery.

If you draw the system, the most accurate diagram would show:
- public source platforms on one side,
- a GitHub Actions-backed feed generation service in the middle,
- and a local agent/runtime with prompt-driven summarization and delivery on the other side.

Main entry points: [`scripts/prepare-digest.js`](https://github.com/zarazhangrui/follow-builders/blob/main/scripts/prepare-digest.js) (Prepare digest), [`SKILL.md`](https://github.com/zarazhangrui/follow-builders/blob/main/SKILL.md) (SKILL.md), [`scripts/generate-feed.js`](https://github.com/zarazhangrui/follow-builders/blob/main/scripts/generate-feed.js) (Generate feed), [`config/default-sources.json`](https://github.com/zarazhangrui/follow-builders/blob/main/config/default-sources.json) (Default sources)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_skill["Skill layer"]
  node_skill_md["SKILL.md<br/>skill spec<br/>[SKILL.md]"]
  node_readme_en["README<br/>docs<br/>[README.md]"]
  node_readme_zh["README zh<br/>docs<br/>[README.zh-CN.md]"]
  node_sample_digest["Sample digest<br/>example output<br/>[sample-digest.md]"]
  node_digest_intro["Digest intro<br/>prompt<br/>[digest-intro.md]"]
  node_summarize_blogs["Blog summary<br/>prompt<br/>[summarize-blogs.md]"]
  node_summarize_podcast["Podcast summary<br/>prompt"]
  node_summarize_tweets["Tweet summary<br/>prompt"]
  node_translate_prompt["Translate<br/>prompt<br/>[translate.md]"]
end

subgraph group_group_feed["Central feed"]
  node_default_sources["Default sources<br/>source registry"]
  node_feed_blogs["Blog feed<br/>feed input<br/>[feed-blogs.json]"]
  node_feed_podcasts["Podcast feed<br/>feed input<br/>[feed-podcasts.json]"]
  node_feed_x["X feed<br/>feed input<br/>[feed-x.json]"]
  node_generate_workflow["Feed workflow<br/>github action<br/>[generate-feed.yml]"]
  node_generate_script["Generate feed<br/>node script<br/>[generate-feed.js]"]
  node_state_feed[("Feed state<br/>[state-feed.json]")]
end

subgraph group_group_local["Local orchestration"]
  node_config_schema["Config schema<br/>[config-schema.json]"]
  node_prepare_digest["Prepare digest<br/>node script<br/>[prepare-digest.js]"]
  node_deliver_script["Deliver<br/>node script<br/>[deliver.js]"]
  node_scripts_pkg["Scripts pkg<br/>node package<br/>[package.json]"]
end

node_skill_md -->|"guides"| node_digest_intro
node_skill_md -->|"guides"| node_summarize_blogs
node_skill_md -->|"guides"| node_summarize_podcast
node_skill_md -->|"guides"| node_summarize_tweets
node_skill_md -->|"guides"| node_translate_prompt
node_readme_en -->|"documents"| node_skill_md
node_readme_zh -->|"documents"| node_skill_md
node_sample_digest -->|"shows"| node_digest_intro
node_default_sources -->|"drives"| node_feed_blogs
node_default_sources -->|"drives"| node_feed_podcasts
node_default_sources -->|"drives"| node_feed_x
node_generate_workflow -->|"runs"| node_generate_script
node_generate_script -->|"updates"| node_state_feed
node_generate_script -->|"builds"| node_feed_blogs
node_generate_script -->|"builds"| node_feed_podcasts
node_generate_script -->|"builds"| node_feed_x
node_config_schema -->|"validates"| node_prepare_digest
node_scripts_pkg -->|"backs"| node_generate_script
node_scripts_pkg -->|"backs"| node_prepare_digest
node_scripts_pkg -->|"backs"| node_deliver_script
node_feed_blogs -->|"inputs"| node_prepare_digest
node_feed_podcasts -->|"inputs"| node_prepare_digest
node_feed_x -->|"inputs"| node_prepare_digest
node_digest_intro -->|"frames"| node_prepare_digest
node_summarize_blogs -->|"summarizes"| node_prepare_digest
node_summarize_podcast -->|"summarizes"| node_prepare_digest
node_summarize_tweets -->|"summarizes"| node_prepare_digest
node_translate_prompt -->|"translates"| node_prepare_digest
node_prepare_digest -->|"hands off"| node_deliver_script

click node_skill_md "https://github.com/zarazhangrui/follow-builders/blob/main/SKILL.md"
click node_readme_en "https://github.com/zarazhangrui/follow-builders/blob/main/README.md"
click node_readme_zh "https://github.com/zarazhangrui/follow-builders/blob/main/README.zh-CN.md"
click node_sample_digest "https://github.com/zarazhangrui/follow-builders/blob/main/examples/sample-digest.md"
click node_digest_intro "https://github.com/zarazhangrui/follow-builders/blob/main/prompts/digest-intro.md"
click node_summarize_blogs "https://github.com/zarazhangrui/follow-builders/blob/main/prompts/summarize-blogs.md"
click node_summarize_podcast "https://github.com/zarazhangrui/follow-builders/blob/main/prompts/summarize-podcast.md"
click node_summarize_tweets "https://github.com/zarazhangrui/follow-builders/blob/main/prompts/summarize-tweets.md"
click node_translate_prompt "https://github.com/zarazhangrui/follow-builders/blob/main/prompts/translate.md"
click node_default_sources "https://github.com/zarazhangrui/follow-builders/blob/main/config/default-sources.json"
click node_feed_blogs "https://github.com/zarazhangrui/follow-builders/blob/main/feed-blogs.json"
click node_feed_podcasts "https://github.com/zarazhangrui/follow-builders/blob/main/feed-podcasts.json"
click node_feed_x "https://github.com/zarazhangrui/follow-builders/blob/main/feed-x.json"
click node_generate_workflow "https://github.com/zarazhangrui/follow-builders/blob/main/.github/workflows/generate-feed.yml"
click node_generate_script "https://github.com/zarazhangrui/follow-builders/blob/main/scripts/generate-feed.js"
click node_state_feed "https://github.com/zarazhangrui/follow-builders/blob/main/state-feed.json"
click node_config_schema "https://github.com/zarazhangrui/follow-builders/blob/main/config/config-schema.json"
click node_prepare_digest "https://github.com/zarazhangrui/follow-builders/blob/main/scripts/prepare-digest.js"
click node_deliver_script "https://github.com/zarazhangrui/follow-builders/blob/main/scripts/deliver.js"
click node_scripts_pkg "https://github.com/zarazhangrui/follow-builders/blob/main/scripts/package.json"

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_skill_md,node_readme_en,node_readme_zh,node_sample_digest,node_digest_intro,node_summarize_blogs,node_summarize_podcast,node_summarize_tweets,node_translate_prompt toneBlue
class node_default_sources,node_feed_blogs,node_feed_podcasts,node_feed_x,node_generate_workflow,node_generate_script,node_state_feed toneAmber
class node_config_schema,node_prepare_digest,node_deliver_script,node_scripts_pkg toneMint
```

## Components

### Skill layer

Agent-facing guidance, prompts, and examples that shape digest behavior.

- [SKILL.md](https://github.com/zarazhangrui/follow-builders/blob/main/SKILL.md): skill spec · Primary agent-facing operating instructions for the Follow Builders skill. · `SKILL.md`
- [README](https://github.com/zarazhangrui/follow-builders/blob/main/README.md): docs · English overview of the workflow, architecture, and setup. · `README.md`
- [README zh](https://github.com/zarazhangrui/follow-builders/blob/main/README.zh-CN.md): docs · Chinese documentation for the same skill and workflow. · `README.zh-CN.md`
- [Sample digest](https://github.com/zarazhangrui/follow-builders/blob/main/examples/sample-digest.md): example output · Reference digest showing the expected shape and tone of generated output. · `examples/sample-digest.md`
- [Digest intro](https://github.com/zarazhangrui/follow-builders/blob/main/prompts/digest-intro.md): prompt · Top-level framing and tone for the final digest. · `prompts/digest-intro.md`
- [Blog summary](https://github.com/zarazhangrui/follow-builders/blob/main/prompts/summarize-blogs.md): prompt · Summarization rules for blog content. · `prompts/summarize-blogs.md`
- [Podcast summary](https://github.com/zarazhangrui/follow-builders/blob/main/prompts/summarize-podcast.md): prompt · Summarization rules for podcast content. · `prompts/summarize-podcast.md`
- [Tweet summary](https://github.com/zarazhangrui/follow-builders/blob/main/prompts/summarize-tweets.md): prompt · Summarization rules for X/Twitter content. · `prompts/summarize-tweets.md`
- [Translate](https://github.com/zarazhangrui/follow-builders/blob/main/prompts/translate.md): prompt · Translation and bilingual output behavior. · `prompts/translate.md`

### Central feed

Shared upstream feed generation and canonical source definitions.

- [Default sources](https://github.com/zarazhangrui/follow-builders/blob/main/config/default-sources.json): source registry · Canonical curated source set used by the skill. · `config/default-sources.json`
- [Blog feed](https://github.com/zarazhangrui/follow-builders/blob/main/feed-blogs.json): feed input · Blog source feed artifact or cached input. · `feed-blogs.json`
- [Podcast feed](https://github.com/zarazhangrui/follow-builders/blob/main/feed-podcasts.json): feed input · Podcast source feed artifact or cached input. · `feed-podcasts.json`
- [X feed](https://github.com/zarazhangrui/follow-builders/blob/main/feed-x.json): feed input · X/Twitter source feed artifact or cached input. · `feed-x.json`
- [Feed workflow](https://github.com/zarazhangrui/follow-builders/blob/main/.github/workflows/generate-feed.yml): github action · Scheduled automation that runs central feed generation. · `.github/workflows/generate-feed.yml`
- [Generate feed](https://github.com/zarazhangrui/follow-builders/blob/main/scripts/generate-feed.js): node script · Main generator that builds the shared feed from public sources. · `scripts/generate-feed.js`
- [Feed state](https://github.com/zarazhangrui/follow-builders/blob/main/state-feed.json): state · Incremental generation or deduplication state for the shared feed. · `state-feed.json`

### Local orchestration

User-side digest preparation and delivery workflow.

- [Config schema](https://github.com/zarazhangrui/follow-builders/blob/main/config/config-schema.json): schema · Validation schema for user settings and delivery preferences. · `config/config-schema.json`
- [Prepare digest](https://github.com/zarazhangrui/follow-builders/blob/main/scripts/prepare-digest.js): node script · Builds a user-specific digest from the shared feed and preferences. · `scripts/prepare-digest.js`
- [Deliver](https://github.com/zarazhangrui/follow-builders/blob/main/scripts/deliver.js): node script · Sends the prepared digest to the selected destination. · `scripts/deliver.js`
- [Scripts pkg](https://github.com/zarazhangrui/follow-builders/blob/main/scripts/package.json): node package · Runtime/package metadata for the Node-based orchestration scripts. · `scripts/package.json`

## Connections

- SKILL.md → Digest intro: guides · Skill instructions are implemented through the digest framing prompt.
- SKILL.md → Blog summary: guides · Skill behavior includes blog-specific summarization rules.
- SKILL.md → Podcast summary: guides · Skill behavior includes podcast-specific summarization rules.
- SKILL.md → Tweet summary: guides · Skill behavior includes tweet-specific summarization rules.
- SKILL.md → Translate: guides · Skill behavior includes translation and bilingual formatting.
- README → SKILL.md: documents · README explains the agent skill and workflow.
- README zh → SKILL.md: documents · Chinese README documents the same skill.
- Sample digest → Digest intro: shows · Example output demonstrates the digest framing and structure.
- Default sources → Blog feed: drives · Canonical source registry feeds the blog source artifact.
- Default sources → Podcast feed: drives · Canonical source registry feeds the podcast source artifact.
- Default sources → X feed: drives · Canonical source registry feeds the X source artifact.
- Feed workflow → Generate feed: runs · GitHub Actions workflow executes the feed generator.
- Generate feed → Feed state: updates · Generator persists incremental state for continuity and deduping.
- Generate feed → Blog feed: builds · Generator produces the blog feed artifact.
- Generate feed → Podcast feed: builds · Generator produces the podcast feed artifact.
- Generate feed → X feed: builds · Generator produces the X feed artifact.
- Config schema → Prepare digest: validates · User configuration is validated before digest preparation.
- Scripts pkg → Generate feed: backs · Node runtime/package metadata backs the generator script.
- Scripts pkg → Prepare digest: backs · Node runtime/package metadata backs the digest preparer.
- Scripts pkg → Deliver: backs · Node runtime/package metadata backs the delivery script.
- Blog feed → Prepare digest: inputs · Prepared digest consumes blog items from the shared feed.
- Podcast feed → Prepare digest: inputs · Prepared digest consumes podcast items from the shared feed.
- X feed → Prepare digest: inputs · Prepared digest consumes X items from the shared feed.
- Digest intro → Prepare digest: frames · Digest preparation applies the top-level tone and layout.
- Blog summary → Prepare digest: summarizes · Blog prompt is used during digest assembly.
- Podcast summary → Prepare digest: summarizes · Podcast prompt is used during digest assembly.
- Tweet summary → Prepare digest: summarizes · Tweet prompt is used during digest assembly.
- Translate → Prepare digest: translates · Translation prompt is applied when language preferences require it.
- Prepare digest → Deliver: hands off · Prepared digest is passed to delivery.
