# joolaoye/pulse architecture

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

- Interactive diagram: https://gitdiagram.com/joolaoye/pulse
- Repository: https://github.com/joolaoye/pulse

## Overview

Pulse turns a configured X list and interest profile into a generated podcast episode and RSS feed. Users configure shows, pipelines, and schedules through the CLI, then run manually or on a schedule. The documented episode workflow retrieves conversations, filters and groups signals, plans and scripts an episode, synthesizes audio, and publishes it. The graph also includes configuration, orchestration, and Cloudflare persistence/runtime capabilities. Workflow edges are based on README statements; sampled source confirms selected configuration and runtime wiring, but not every processing-stage connection.

Main entry points: [`src/pulse/application/orchestration/runner/workflow_runner.py`](https://github.com/joolaoye/pulse/blob/main/src/pulse/application/orchestration/runner/workflow_runner.py) (Workflow Orchestrator), [`src/pulse/cli/main.py`](https://github.com/joolaoye/pulse/blob/main/src/pulse/cli/main.py) (Pulse CLI), [`src/pulse/application/execution/run_manager.py`](https://github.com/joolaoye/pulse/blob/main/src/pulse/application/execution/run_manager.py) (Run Manager), [`src/pulse/infrastructure/db/repositories/pipeline.py`](https://github.com/joolaoye/pulse/blob/main/src/pulse/infrastructure/db/repositories/pipeline.py) (D1 Repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Show Configuration"]
  node_cli["Pulse CLI<br/>[main.py]"]
  node_show["Show Manager<br/>[show_manager.py]"]
  node_pipeline["Pipeline Manager"]
  node_schedule["Schedule Manager"]
end

subgraph group_workflow["Episode Workflow"]
  node_retrieval["X Retrieval<br/>[x_retriever.py]"]
  node_ingestion["Signal Ingestion<br/>[ingestor.py]"]
  node_semantics["Signal Processing"]
  node_grouping["Theme Grouping"]
end

subgraph group_generation["Episode Generation"]
  node_planning["Episode Planning<br/>[episode_planner.py]"]
  node_scripting["Script Generation"]
  node_audio["Audio Production<br/>[producer.py]"]
  node_publishing["Podcast Publishing"]
end

subgraph group_platform["Runtime Platform"]
  node_run["Run Manager<br/>[run_manager.py]"]
  node_orchestrator["Workflow Orchestrator<br/>[workflow_runner.py]"]
  node_d1[("Cloudflare D1<br/>[client.py]")]
  node_repositories["D1 Repositories<br/>[pipeline.py]"]
  node_vector[("Vectorize Store<br/>[client.py]")]
  node_objectstore[("R2 Object Store<br/>[object_store.py]")]
  node_cloudflare["Cloudflare Runtime<br/>[workflow.py]"]
end

node_user(("Show Operator"))
node_xservice["X API"]
node_anthropic["Anthropic"]
node_voyage["Voyage AI"]
node_elevenlabs["ElevenLabs"]
node_podcastclient(("Podcast Client"))

node_user -->|"configures and runs"| node_cli
node_cli -->|"manages shows"| node_show
node_cli -->|"manages pipelines"| node_pipeline
node_cli -->|"manages schedules"| node_schedule
node_cli -.->|"runs manually"| node_run
node_show -.->|"persists show"| node_repositories
node_pipeline -->|"persists pipeline"| node_repositories
node_schedule -.->|"persists schedule"| node_repositories
node_schedule -.->|"dispatches scheduled run"| node_run
node_cloudflare -.->|"triggers workflow"| node_run
node_run -->|"starts or resumes"| node_orchestrator
node_orchestrator -->|"retrieves conversations"| node_retrieval
node_orchestrator -->|"deduplicates signals"| node_ingestion
node_orchestrator -->|"filters and scores"| node_semantics
node_orchestrator -->|"groups themes"| node_grouping
node_orchestrator -->|"plans episode"| node_planning
node_orchestrator -->|"writes episode"| node_scripting
node_orchestrator -->|"generates speech"| node_audio
node_orchestrator -->|"publishes episode"| node_publishing
node_retrieval -->|"retrieves posts"| node_xservice
node_planning -->|"uses language model"| node_anthropic
node_scripting -->|"uses language model"| node_anthropic
node_semantics -->|"embeds signals"| node_voyage
node_audio -->|"synthesizes speech"| node_elevenlabs
node_publishing -->|"stores feed and audio"| node_objectstore
node_podcastclient -->|"consumes public feed"| node_objectstore
node_orchestrator -.->|"checkpoints runs"| node_d1
node_orchestrator -.->|"uses semantic history"| node_vector
node_repositories -->|"queries and writes"| node_d1

click node_cli "https://github.com/joolaoye/pulse/blob/main/src/pulse/cli/main.py"
click node_show "https://github.com/joolaoye/pulse/blob/main/src/pulse/application/configuration/show_manager.py"
click node_pipeline "https://github.com/joolaoye/pulse/blob/main/src/pulse/application/configuration/pipeline_manager.py"
click node_schedule "https://github.com/joolaoye/pulse/blob/main/src/pulse/application/configuration/schedule_manager.py"
click node_run "https://github.com/joolaoye/pulse/blob/main/src/pulse/application/execution/run_manager.py"
click node_orchestrator "https://github.com/joolaoye/pulse/blob/main/src/pulse/application/orchestration/runner/workflow_runner.py"
click node_retrieval "https://github.com/joolaoye/pulse/blob/main/src/pulse/services/retrieval/x_retriever.py"
click node_ingestion "https://github.com/joolaoye/pulse/blob/main/src/pulse/services/ingestion/ingestor.py"
click node_semantics "https://github.com/joolaoye/pulse/blob/main/src/pulse/services/signals/semantic_processor.py"
click node_grouping "https://github.com/joolaoye/pulse/blob/main/src/pulse/services/grouping/signal_group_builder.py"
click node_planning "https://github.com/joolaoye/pulse/blob/main/src/pulse/services/planning/episode_planner.py"
click node_scripting "https://github.com/joolaoye/pulse/blob/main/src/pulse/services/scripting/script_generator.py"
click node_audio "https://github.com/joolaoye/pulse/blob/main/src/pulse/services/audio/producer.py"
click node_publishing "https://github.com/joolaoye/pulse/blob/main/src/pulse/services/publishing/podcast_publisher.py"
click node_d1 "https://github.com/joolaoye/pulse/blob/main/src/pulse/infrastructure/db/d1/client.py"
click node_repositories "https://github.com/joolaoye/pulse/blob/main/src/pulse/infrastructure/db/repositories/pipeline.py"
click node_vector "https://github.com/joolaoye/pulse/blob/main/src/pulse/infrastructure/vector/vectorize/client.py"
click node_objectstore "https://github.com/joolaoye/pulse/blob/main/src/pulse/infrastructure/storage/r2/object_store.py"
click node_cloudflare "https://github.com/joolaoye/pulse/blob/main/src/pulse/infrastructure/cloudflare/workflow.py"

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_cli,node_show,node_pipeline,node_schedule,node_podcastclient toneBlue
class node_retrieval,node_ingestion,node_semantics,node_grouping toneAmber
class node_planning,node_scripting,node_audio,node_publishing,node_xservice toneMint
class node_run,node_orchestrator,node_d1,node_repositories,node_vector,node_objectstore,node_cloudflare toneRose
class node_user,node_anthropic,node_voyage,node_elevenlabs toneIndigo
```

## Components

### Show Configuration

- [Pulse CLI](https://github.com/joolaoye/pulse/blob/main/src/pulse/cli/main.py): `src/pulse/cli/main.py`
- [Show Manager](https://github.com/joolaoye/pulse/blob/main/src/pulse/application/configuration/show_manager.py): `src/pulse/application/configuration/show_manager.py`
- [Pipeline Manager](https://github.com/joolaoye/pulse/blob/main/src/pulse/application/configuration/pipeline_manager.py): `src/pulse/application/configuration/pipeline_manager.py`
- [Schedule Manager](https://github.com/joolaoye/pulse/blob/main/src/pulse/application/configuration/schedule_manager.py): `src/pulse/application/configuration/schedule_manager.py`

### Episode Workflow

- [X Retrieval](https://github.com/joolaoye/pulse/blob/main/src/pulse/services/retrieval/x_retriever.py): `src/pulse/services/retrieval/x_retriever.py`
- [Signal Ingestion](https://github.com/joolaoye/pulse/blob/main/src/pulse/services/ingestion/ingestor.py): `src/pulse/services/ingestion/ingestor.py`
- [Signal Processing](https://github.com/joolaoye/pulse/blob/main/src/pulse/services/signals/semantic_processor.py): `src/pulse/services/signals/semantic_processor.py`
- [Theme Grouping](https://github.com/joolaoye/pulse/blob/main/src/pulse/services/grouping/signal_group_builder.py): `src/pulse/services/grouping/signal_group_builder.py`

### Episode Generation

- [Episode Planning](https://github.com/joolaoye/pulse/blob/main/src/pulse/services/planning/episode_planner.py): `src/pulse/services/planning/episode_planner.py`
- [Script Generation](https://github.com/joolaoye/pulse/blob/main/src/pulse/services/scripting/script_generator.py): `src/pulse/services/scripting/script_generator.py`
- [Audio Production](https://github.com/joolaoye/pulse/blob/main/src/pulse/services/audio/producer.py): `src/pulse/services/audio/producer.py`
- [Podcast Publishing](https://github.com/joolaoye/pulse/blob/main/src/pulse/services/publishing/podcast_publisher.py): `src/pulse/services/publishing/podcast_publisher.py`

### Runtime Platform

- [Run Manager](https://github.com/joolaoye/pulse/blob/main/src/pulse/application/execution/run_manager.py): `src/pulse/application/execution/run_manager.py`
- [Workflow Orchestrator](https://github.com/joolaoye/pulse/blob/main/src/pulse/application/orchestration/runner/workflow_runner.py): `src/pulse/application/orchestration/runner/workflow_runner.py`
- [Cloudflare D1](https://github.com/joolaoye/pulse/blob/main/src/pulse/infrastructure/db/d1/client.py): `src/pulse/infrastructure/db/d1/client.py`
- [D1 Repositories](https://github.com/joolaoye/pulse/blob/main/src/pulse/infrastructure/db/repositories/pipeline.py): `src/pulse/infrastructure/db/repositories/pipeline.py`
- [Vectorize Store](https://github.com/joolaoye/pulse/blob/main/src/pulse/infrastructure/vector/vectorize/client.py): `src/pulse/infrastructure/vector/vectorize/client.py`
- [R2 Object Store](https://github.com/joolaoye/pulse/blob/main/src/pulse/infrastructure/storage/r2/object_store.py): `src/pulse/infrastructure/storage/r2/object_store.py`
- [Cloudflare Runtime](https://github.com/joolaoye/pulse/blob/main/src/pulse/infrastructure/cloudflare/workflow.py): `src/pulse/infrastructure/cloudflare/workflow.py`

### Other components

- **Show Operator**
- **X API**
- **Anthropic**
- **Voyage AI**
- **ElevenLabs**
- **Podcast Client**

## Connections

- Show Operator → Pulse CLI: configures and runs (evidence: `README.md`)
- Pulse CLI → Show Manager: manages shows (evidence: `src/pulse/cli/main.py`)
- Pulse CLI → Pipeline Manager: manages pipelines (evidence: `src/pulse/cli/main.py`)
- Pulse CLI → Schedule Manager: manages schedules (evidence: `src/pulse/cli/main.py`)
- Pulse CLI → Run Manager: runs manually (evidence: `README.md`)
- Show Manager → D1 Repositories: persists show
- Pipeline Manager → D1 Repositories: persists pipeline (evidence: `src/pulse/application/configuration/pipeline_manager.py`)
- Schedule Manager → D1 Repositories: persists schedule
- Schedule Manager → Run Manager: dispatches scheduled run
- Cloudflare Runtime → Run Manager: triggers workflow (evidence: `README.md`)
- Run Manager → Workflow Orchestrator: starts or resumes (evidence: `src/pulse/application/execution/run_manager.py`)
- Workflow Orchestrator → X Retrieval: retrieves conversations (evidence: `README.md`)
- Workflow Orchestrator → Signal Ingestion: deduplicates signals (evidence: `README.md`)
- Workflow Orchestrator → Signal Processing: filters and scores (evidence: `README.md`)
- Workflow Orchestrator → Theme Grouping: groups themes (evidence: `README.md`)
- Workflow Orchestrator → Episode Planning: plans episode (evidence: `README.md`)
- Workflow Orchestrator → Script Generation: writes episode (evidence: `README.md`)
- Workflow Orchestrator → Audio Production: generates speech (evidence: `README.md`)
- Workflow Orchestrator → Podcast Publishing: publishes episode (evidence: `README.md`)
- X Retrieval → X API: retrieves posts (evidence: `README.md`)
- Episode Planning → Anthropic: uses language model (evidence: `README.md`)
- Script Generation → Anthropic: uses language model (evidence: `README.md`)
- Signal Processing → Voyage AI: embeds signals (evidence: `README.md`)
- Audio Production → ElevenLabs: synthesizes speech (evidence: `README.md`)
- Podcast Publishing → R2 Object Store: stores feed and audio (evidence: `README.md`)
- Podcast Client → R2 Object Store: consumes public feed (evidence: `README.md`)
- Workflow Orchestrator → Cloudflare D1: checkpoints runs (evidence: `README.md`)
- Workflow Orchestrator → Vectorize Store: uses semantic history (evidence: `README.md`)
- D1 Repositories → Cloudflare D1: queries and writes (evidence: `src/pulse/infrastructure/db/repositories/pipeline.py`)
