# dylanddeng/bubbles-brain architecture

> Architecture diagram of the GitHub repository dylanddeng/bubbles-brain, 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/dylanddeng/bubbles-brain
- Repository: https://github.com/dylanddeng/bubbles-brain

## Overview

Bubble’s Brain is an Astro-based bilingual knowledge site for AI practitioners, centered on evergreen, reusable content rather than a live news feed. The visitor workflow is to browse or search articles, with RSS and sitemap as alternate discovery outputs; community comments and authentication are supporting capabilities. Content is maintained in Markdown and a separate Workers publishing pipeline supports publication. README documents the site capabilities, while source-index references show several Worker-to-storage dependencies; unsampled Worker internals are not inferred. The retired daily-news pipeline is excluded.

Main entry points: [`astro/astro.config.mjs`](https://github.com/dylanddeng/bubbles-brain/blob/main/astro/astro.config.mjs) (Astro site), [`workers/content/shared/db.ts`](https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/shared/db.ts) (Publishing database), [`workers/content/editorial/index.ts`](https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/editorial/index.ts) (Editorial worker), [`workers/content/ingestion/mirror.ts`](https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/ingestion/mirror.ts) (Content ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_site["Knowledge site"]
  node_site["Astro site<br/>[astro.config.mjs]"]
  node_content["Markdown collections<br/>[content.config.ts]"]
  node_routes["Bilingual sections"]
  node_search["Full-text search<br/>[searchIndex.ts]"]
  node_feeds["RSS and sitemap<br/>[rss.xml.ts]"]
end

subgraph group_community["Community features"]
  node_communityui["Comments UI"]
  node_supabase["Supabase client<br/>[client.ts]"]
  node_communityconfig["Community config<br/>[config.ts]"]
  node_auth["User auth<br/>[authStore.ts]"]
end

subgraph group_publishing["Content publishing"]
  node_editorial["Editorial worker<br/>[index.ts]"]
  node_broker["Publishing broker<br/>[index.ts]"]
  node_mirror["Content ingestion<br/>[mirror.ts]"]
  node_deployer["Content deployer<br/>[index.ts]"]
end

subgraph group_storage["Publishing storage"]
  node_canonical["Canonical content<br/>[canonical.ts]"]
  node_db[("Publishing database<br/>[db.ts]")]
  node_r2[("Artifact storage<br/>[r2.ts]")]
end

node_visitor(("Reader"))

node_visitor -->|"browses"| node_site
node_site -->|"renders"| node_content
node_site -->|"routes through"| node_routes
node_site -->|"provides search"| node_search
node_site -->|"generates feeds"| node_feeds
node_site -.->|"offers comments"| node_communityui
node_communityui -.->|"uses client"| node_supabase
node_supabase -->|"loads config"| node_communityconfig
node_communityui -.->|"supports sign-in"| node_auth
node_editorial -->|"uses canonical data"| node_canonical
node_editorial -->|"reads and writes"| node_db
node_editorial -->|"uses artifacts"| node_r2
node_broker -->|"reads and writes"| node_db
node_mirror -->|"uses canonical data"| node_canonical
node_mirror -->|"reads and writes"| node_db
node_mirror -->|"uses artifacts"| node_r2
node_deployer -->|"uses canonical data"| node_canonical
node_deployer -->|"reads and writes"| node_db
node_deployer -->|"uses artifacts"| node_r2

click node_site "https://github.com/dylanddeng/bubbles-brain/blob/main/astro/astro.config.mjs"
click node_content "https://github.com/dylanddeng/bubbles-brain/blob/main/astro/src/content.config.ts"
click node_routes "https://github.com/dylanddeng/bubbles-brain/blob/main/astro/src/lib/collectionRoutes.ts"
click node_search "https://github.com/dylanddeng/bubbles-brain/blob/main/astro/src/lib/searchIndex.ts"
click node_feeds "https://github.com/dylanddeng/bubbles-brain/blob/main/astro/src/pages/rss.xml.ts"
click node_communityui "https://github.com/dylanddeng/bubbles-brain/blob/main/static/js/supabase-comments.js"
click node_supabase "https://github.com/dylanddeng/bubbles-brain/blob/main/astro/src/lib/supabase/client.ts"
click node_communityconfig "https://github.com/dylanddeng/bubbles-brain/blob/main/astro/src/lib/community/config.ts"
click node_auth "https://github.com/dylanddeng/bubbles-brain/blob/main/astro/src/lib/auth/authStore.ts"
click node_editorial "https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/editorial/index.ts"
click node_broker "https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/broker/index.ts"
click node_mirror "https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/ingestion/mirror.ts"
click node_deployer "https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/deployer/index.ts"
click node_canonical "https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/shared/canonical.ts"
click node_db "https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/shared/db.ts"
click node_r2 "https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/shared/r2.ts"

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_site,node_content,node_routes,node_search,node_feeds toneBlue
class node_communityui,node_supabase,node_communityconfig,node_auth toneAmber
class node_editorial,node_broker,node_mirror,node_deployer toneMint
class node_canonical,node_db,node_r2 toneRose
class node_visitor toneIndigo
```

## Components

### Knowledge site

- [Astro site](https://github.com/dylanddeng/bubbles-brain/blob/main/astro/astro.config.mjs): `astro/astro.config.mjs`
- [Markdown collections](https://github.com/dylanddeng/bubbles-brain/blob/main/astro/src/content.config.ts): `astro/src/content.config.ts`
- [Bilingual sections](https://github.com/dylanddeng/bubbles-brain/blob/main/astro/src/lib/collectionRoutes.ts): `astro/src/lib/collectionRoutes.ts`
- [Full-text search](https://github.com/dylanddeng/bubbles-brain/blob/main/astro/src/lib/searchIndex.ts): `astro/src/lib/searchIndex.ts`
- [RSS and sitemap](https://github.com/dylanddeng/bubbles-brain/blob/main/astro/src/pages/rss.xml.ts): `astro/src/pages/rss.xml.ts`

### Community features

- [Comments UI](https://github.com/dylanddeng/bubbles-brain/blob/main/static/js/supabase-comments.js): `static/js/supabase-comments.js`
- [Supabase client](https://github.com/dylanddeng/bubbles-brain/blob/main/astro/src/lib/supabase/client.ts): `astro/src/lib/supabase/client.ts`
- [Community config](https://github.com/dylanddeng/bubbles-brain/blob/main/astro/src/lib/community/config.ts): `astro/src/lib/community/config.ts`
- [User auth](https://github.com/dylanddeng/bubbles-brain/blob/main/astro/src/lib/auth/authStore.ts): `astro/src/lib/auth/authStore.ts`

### Content publishing

- [Editorial worker](https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/editorial/index.ts): `workers/content/editorial/index.ts`
- [Publishing broker](https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/broker/index.ts): `workers/content/broker/index.ts`
- [Content ingestion](https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/ingestion/mirror.ts): `workers/content/ingestion/mirror.ts`
- [Content deployer](https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/deployer/index.ts): `workers/content/deployer/index.ts`

### Publishing storage

- [Canonical content](https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/shared/canonical.ts): `workers/content/shared/canonical.ts`
- [Publishing database](https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/shared/db.ts): `workers/content/shared/db.ts`
- [Artifact storage](https://github.com/dylanddeng/bubbles-brain/blob/main/workers/content/shared/r2.ts): `workers/content/shared/r2.ts`

### Other components

- **Reader**

## Connections

- Reader → Astro site: browses (evidence: `README.md`)
- Astro site → Markdown collections: renders (evidence: `README.md`)
- Astro site → Bilingual sections: routes through (evidence: `README.md`)
- Astro site → Full-text search: provides search (evidence: `README.md`)
- Astro site → RSS and sitemap: generates feeds (evidence: `README.md`)
- Astro site → Comments UI: offers comments
- Comments UI → Supabase client: uses client
- Supabase client → Community config: loads config (evidence: `astro/src/lib/supabase/client.ts`)
- Comments UI → User auth: supports sign-in
- Editorial worker → Canonical content: uses canonical data (evidence: `workers/content/editorial/index.ts`)
- Editorial worker → Publishing database: reads and writes (evidence: `workers/content/editorial/index.ts`)
- Editorial worker → Artifact storage: uses artifacts (evidence: `workers/content/editorial/index.ts`)
- Publishing broker → Publishing database: reads and writes (evidence: `workers/content/broker/index.ts`)
- Content ingestion → Canonical content: uses canonical data (evidence: `workers/content/ingestion/mirror.ts`)
- Content ingestion → Publishing database: reads and writes (evidence: `workers/content/ingestion/mirror.ts`)
- Content ingestion → Artifact storage: uses artifacts (evidence: `workers/content/ingestion/mirror.ts`)
- Content deployer → Canonical content: uses canonical data (evidence: `workers/content/deployer/index.ts`)
- Content deployer → Publishing database: reads and writes (evidence: `workers/content/deployer/index.ts`)
- Content deployer → Artifact storage: uses artifacts (evidence: `workers/content/deployer/index.ts`)
