# buchidonggua/dg-ai-notes architecture

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

- Interactive diagram: https://gitdiagram.com/buchidonggua/dg-ai-notes
- Repository: https://github.com/buchidonggua/dg-ai-notes

## Overview

This repository is an educational resource about the Pi-Agent SDK, not the SDK runtime itself. Its main reader workflow is to study the source-dive chapters or follow the hands-on DataAgent lessons, using the web book and interactive demonstrations as learning surfaces; a companion skill provides SDK and scenario references. The README documents these content tracks, while source excerpts show selected demo-to-data and component-to-helper relationships. The tutorials describe runtime behavior, but the underlying Pi-Agent SDK is external to this repository.

Main entry points: [`pi-agent/web/src/components/islands/PartialMessageTimeline.tsx`](https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/components/islands/PartialMessageTimeline.tsx) (Message Timeline), [`pi-agent/web/src/pages/index.astro`](https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/pages/index.astro) (Online Book), [`skills/dg-piagent/SKILL.md`](https://github.com/buchidonggua/dg-ai-notes/blob/main/skills/dg-piagent/SKILL.md) (Skill Guide), [`pi-agent/web/src/components/islands/KnowledgeGraph.tsx`](https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/components/islands/KnowledgeGraph.tsx) (Knowledge Graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Book"]
  node_book["Online Book<br/>[index.astro]"]
  node_chapters["Chapter Content"]
  node_knowledge["Knowledge Graph<br/>[KnowledgeGraph.tsx]"]
  node_moduledata["Module Graph Data<br/>[module-graph.ts]"]
  node_partialdemo["Message Timeline"]
  node_errordemo["Error Defense Demo"]
  node_timeline["Event Timeline<br/>[EventTimeline.tsx]"]
  node_controls["Play Controls<br/>[PlayControls.tsx]"]
  node_messagecard["Message Card<br/>[MessageCard.tsx]"]
end

subgraph group_source["Source Dive"]
  node_tsbook["TypeScript Chapters"]
  node_pybook["Python Chapters"]
end

subgraph group_practice["Hands-on Lessons"]
  node_lessons["Tutorial Lessons"]
  node_examples["Runnable Examples"]
  node_querytool["Sales Query Tool<br/>[query-data.ts]"]
  node_sse["SSE DataAgent<br/>[07a-sse-server.ts]"]
end

subgraph group_skill["Developer Skill"]
  node_skillguide["Skill Guide<br/>[SKILL.md]"]
  node_sdkrefs["SDK References"]
  node_scenarios["Scenario Guides"]
end

node_reader(("Learner"))

node_reader -->|"reads online"| node_book
node_reader -->|"studies TypeScript"| node_tsbook
node_reader -->|"studies Python"| node_pybook
node_reader -->|"follows lessons"| node_lessons
node_reader -->|"uses skill"| node_skillguide
node_book -->|"presents chapters"| node_chapters
node_book -->|"offers interactive graph"| node_knowledge
node_knowledge -->|"reads graph data"| node_moduledata
node_partialdemo -->|"renders events"| node_timeline
node_partialdemo -->|"renders controls"| node_controls
node_partialdemo -->|"renders snapshots"| node_messagecard
node_errordemo -->|"renders events"| node_timeline
node_lessons -->|"pairs with code"| node_examples
node_examples -->|"includes shared tool"| node_querytool
node_sse -->|"registers tool"| node_querytool
node_skillguide -->|"organizes references"| node_sdkrefs
node_skillguide -->|"organizes scenarios"| node_scenarios

click node_book "https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/pages/index.astro"
click node_chapters "https://github.com/buchidonggua/dg-ai-notes/tree/main/pi-agent/web/src/content/modules"
click node_knowledge "https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/components/islands/KnowledgeGraph.tsx"
click node_moduledata "https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/data/module-graph.ts"
click node_partialdemo "https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/components/islands/PartialMessageTimeline.tsx"
click node_errordemo "https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/components/islands/ErrorDefenseDemo.tsx"
click node_timeline "https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/components/islands/shared/EventTimeline.tsx"
click node_controls "https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/components/islands/shared/PlayControls.tsx"
click node_messagecard "https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/components/islands/shared/MessageCard.tsx"
click node_tsbook "https://github.com/buchidonggua/dg-ai-notes/tree/main/pi-agent/pi_source_dive/typescript"
click node_pybook "https://github.com/buchidonggua/dg-ai-notes/tree/main/pi-agent/pi_source_dive/python"
click node_lessons "https://github.com/buchidonggua/dg-ai-notes/tree/main/pi-agent/pi_sdk_learn/docs"
click node_examples "https://github.com/buchidonggua/dg-ai-notes/tree/main/pi-agent/pi_sdk_learn/code"
click node_querytool "https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/pi_sdk_learn/code/shared/lib/tools/query-data.ts"
click node_sse "https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/pi_sdk_learn/code/L07-streaming/07a-sse-server.ts"
click node_skillguide "https://github.com/buchidonggua/dg-ai-notes/blob/main/skills/dg-piagent/SKILL.md"
click node_sdkrefs "https://github.com/buchidonggua/dg-ai-notes/tree/main/skills/dg-piagent/references/sdk_doc"
click node_scenarios "https://github.com/buchidonggua/dg-ai-notes/tree/main/skills/dg-piagent/references/scenarios"

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_book,node_chapters,node_knowledge,node_moduledata,node_partialdemo,node_errordemo,node_timeline,node_controls,node_messagecard toneBlue
class node_tsbook,node_pybook toneAmber
class node_lessons,node_examples,node_querytool,node_sse toneMint
class node_skillguide,node_sdkrefs,node_scenarios toneRose
class node_reader toneIndigo
```

## Components

### Web Book

- [Online Book](https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/pages/index.astro): `pi-agent/web/src/pages/index.astro`
- [Chapter Content](https://github.com/buchidonggua/dg-ai-notes/tree/main/pi-agent/web/src/content/modules): `pi-agent/web/src/content/modules`
- [Knowledge Graph](https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/components/islands/KnowledgeGraph.tsx): `pi-agent/web/src/components/islands/KnowledgeGraph.tsx`
- [Module Graph Data](https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/data/module-graph.ts): `pi-agent/web/src/data/module-graph.ts`
- [Message Timeline](https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/components/islands/PartialMessageTimeline.tsx): `pi-agent/web/src/components/islands/PartialMessageTimeline.tsx`
- [Error Defense Demo](https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/components/islands/ErrorDefenseDemo.tsx): `pi-agent/web/src/components/islands/ErrorDefenseDemo.tsx`
- [Event Timeline](https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/components/islands/shared/EventTimeline.tsx): `pi-agent/web/src/components/islands/shared/EventTimeline.tsx`
- [Play Controls](https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/components/islands/shared/PlayControls.tsx): `pi-agent/web/src/components/islands/shared/PlayControls.tsx`
- [Message Card](https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/web/src/components/islands/shared/MessageCard.tsx): `pi-agent/web/src/components/islands/shared/MessageCard.tsx`

### Source Dive

- [TypeScript Chapters](https://github.com/buchidonggua/dg-ai-notes/tree/main/pi-agent/pi_source_dive/typescript): `pi-agent/pi_source_dive/typescript`
- [Python Chapters](https://github.com/buchidonggua/dg-ai-notes/tree/main/pi-agent/pi_source_dive/python): `pi-agent/pi_source_dive/python`

### Hands-on Lessons

- [Tutorial Lessons](https://github.com/buchidonggua/dg-ai-notes/tree/main/pi-agent/pi_sdk_learn/docs): `pi-agent/pi_sdk_learn/docs`
- [Runnable Examples](https://github.com/buchidonggua/dg-ai-notes/tree/main/pi-agent/pi_sdk_learn/code): `pi-agent/pi_sdk_learn/code`
- [Sales Query Tool](https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/pi_sdk_learn/code/shared/lib/tools/query-data.ts): `pi-agent/pi_sdk_learn/code/shared/lib/tools/query-data.ts`
- [SSE DataAgent](https://github.com/buchidonggua/dg-ai-notes/blob/main/pi-agent/pi_sdk_learn/code/L07-streaming/07a-sse-server.ts): `pi-agent/pi_sdk_learn/code/L07-streaming/07a-sse-server.ts`

### Developer Skill

- [Skill Guide](https://github.com/buchidonggua/dg-ai-notes/blob/main/skills/dg-piagent/SKILL.md): `skills/dg-piagent/SKILL.md`
- [SDK References](https://github.com/buchidonggua/dg-ai-notes/tree/main/skills/dg-piagent/references/sdk_doc): `skills/dg-piagent/references/sdk_doc`
- [Scenario Guides](https://github.com/buchidonggua/dg-ai-notes/tree/main/skills/dg-piagent/references/scenarios): `skills/dg-piagent/references/scenarios`

### Other components

- **Learner**

## Connections

- Learner → Online Book: reads online (evidence: `README.md`)
- Learner → TypeScript Chapters: studies TypeScript (evidence: `README.md`)
- Learner → Python Chapters: studies Python (evidence: `README.md`)
- Learner → Tutorial Lessons: follows lessons (evidence: `README.md`)
- Learner → Skill Guide: uses skill (evidence: `README.md`)
- Online Book → Chapter Content: presents chapters (evidence: `README.md`)
- Online Book → Knowledge Graph: offers interactive graph (evidence: `README.md`)
- Knowledge Graph → Module Graph Data: reads graph data (evidence: `pi-agent/web/src/components/islands/KnowledgeGraph.tsx`)
- Message Timeline → Event Timeline: renders events (evidence: `pi-agent/web/src/components/islands/PartialMessageTimeline.tsx`)
- Message Timeline → Play Controls: renders controls (evidence: `pi-agent/web/src/components/islands/PartialMessageTimeline.tsx`)
- Message Timeline → Message Card: renders snapshots (evidence: `pi-agent/web/src/components/islands/PartialMessageTimeline.tsx`)
- Error Defense Demo → Event Timeline: renders events (evidence: `pi-agent/web/src/components/islands/ErrorDefenseDemo.tsx`)
- Tutorial Lessons → Runnable Examples: pairs with code (evidence: `README.md`)
- Runnable Examples → Sales Query Tool: includes shared tool (evidence: `README.md`)
- SSE DataAgent → Sales Query Tool: registers tool (evidence: `pi-agent/pi_sdk_learn/code/L07-streaming/07a-sse-server.ts`)
- Skill Guide → SDK References: organizes references (evidence: `README.md`)
- Skill Guide → Scenario Guides: organizes scenarios (evidence: `README.md`)
