architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Architecture Diagramming & Visualization

架构图绘制与可视化

Create, maintain, and reason about pplx-sdk system architecture using Mermaid diagrams.

使用Mermaid图表创建、维护并梳理pplx-sdk的系统架构。

When to use

适用场景

Use this skill when:

Visualizing system architecture or component relationships
Designing a new feature and need to map dependencies
Documenting data flow through the SDK layers
Creating sequence diagrams for API call flows
Analyzing import graphs to detect circular dependencies
Onboarding — generating a visual overview of the codebase
Planning refactors that touch multiple layers

在以下场景中使用本技能：

可视化系统架构或组件关系
设计新功能时需要梳理依赖关系
记录SDK各层之间的数据流
为API调用流程创建序列图
分析导入图以检测循环依赖
入职培训——生成代码库的可视化概览
规划涉及多个层级的重构工作

Instructions

操作步骤

Step 1: Identify Diagram Type

步骤1：选择图表类型

Need	Diagram Type	Mermaid Syntax
Layer overview	Layered block diagram	`block-beta` or `graph TD`
Data flow	Flowchart	`graph LR`
API call sequence	Sequence diagram	`sequenceDiagram`
Class relationships	Class diagram	`classDiagram`
State transitions	State diagram	`stateDiagram-v2`
Component dependencies	Dependency graph	`graph TD`
Deployment / infra	C4 or flowchart	`graph TD` with subgraphs

需求	图表类型	Mermaid语法
层级概览	分层块图	`block-beta` 或 `graph TD`
数据流	流程图	`graph LR`
API调用序列	序列图	`sequenceDiagram`
类关系	类图	`classDiagram`
状态转换	状态图	`stateDiagram-v2`
组件依赖	依赖关系图	`graph TD`
部署/基础设施	C4图或流程图	带subgraph的 `graph TD`

Step 2: Map the Architecture

步骤2：绘制架构分层

The pplx-sdk layered architecture:

mermaid

graph TD
    Client["client.py<br/>PerplexityClient, Conversation"]
    Domain["domain/<br/>models.py, services"]
    Transport["transport/<br/>http.py, sse.py"]
    Shared["shared/<br/>auth.py, logging.py, retry.py"]
    Core["core/<br/>protocols.py, types.py, exceptions.py"]

    Client --> Domain
    Client --> Transport
    Client --> Shared
    Domain --> Transport
    Domain --> Shared
    Domain --> Core
    Transport --> Shared
    Transport --> Core
    Shared --> Core

    style Core fill:#e1f5fe
    style Shared fill:#f3e5f5
    style Transport fill:#fff3e0
    style Domain fill:#e8f5e9
    style Client fill:#fce4ec

pplx-sdk的分层架构：

mermaid

graph TD
    Client["client.py<br/>PerplexityClient, Conversation"]
    Domain["domain/<br/>models.py, services"]
    Transport["transport/<br/>http.py, sse.py"]
    Shared["shared/<br/>auth.py, logging.py, retry.py"]
    Core["core/<br/>protocols.py, types.py, exceptions.py"]

    Client --> Domain
    Client --> Transport
    Client --> Shared
    Domain --> Transport
    Domain --> Shared
    Domain --> Core
    Transport --> Shared
    Transport --> Core
    Shared --> Core

    style Core fill:#e1f5fe
    style Shared fill:#f3e5f5
    style Transport fill:#fff3e0
    style Domain fill:#e8f5e9
    style Client fill:#fce4ec

Step 3: Generate Specific Diagrams

步骤3：生成特定图表

SSE Streaming Sequence

SSE流式传输序列图

mermaid

sequenceDiagram
    participant App as Application
    participant Client as PerplexityClient
    participant Transport as SSETransport
    participant API as perplexity.ai

    App->>Client: ask_stream(query)
    Client->>Transport: stream(payload)
    Transport->>API: POST /rest/sse/perplexity.ask
    loop SSE Events
        API-->>Transport: event: query_progress
        Transport-->>Client: StreamChunk(progress)
        API-->>Transport: event: answer_chunk
        Transport-->>Client: StreamChunk(text)
    end
    API-->>Transport: event: final_response
    Transport-->>Client: StreamChunk(final)
    API-->>Transport: : [end]
    Client-->>App: Entry (complete)

mermaid

sequenceDiagram
    participant App as Application
    participant Client as PerplexityClient
    participant Transport as SSETransport
    participant API as perplexity.ai

    App->>Client: ask_stream(query)
    Client->>Transport: stream(payload)
    Transport->>API: POST /rest/sse/perplexity.ask
    loop SSE Events
        API-->>Transport: event: query_progress
        Transport-->>Client: StreamChunk(progress)
        API-->>Transport: event: answer_chunk
        Transport-->>Client: StreamChunk(text)
    end
    API-->>Transport: event: final_response
    Transport-->>Client: StreamChunk(final)
    API-->>Transport: : [end]
    Client-->>App: Entry (complete)

Exception Hierarchy

异常层级图

mermaid

classDiagram
    class PerplexitySDKError {
        +str message
        +dict details
    }
    class TransportError {
        +int status_code
        +str response_body
    }
    class AuthenticationError {
        401
    }
    class RateLimitError {
        +float retry_after
        429
    }
    class StreamingError
    class ValidationError

    PerplexitySDKError <|-- TransportError
    PerplexitySDKError <|-- StreamingError
    PerplexitySDKError <|-- ValidationError
    TransportError <|-- AuthenticationError
    TransportError <|-- RateLimitError

mermaid

classDiagram
    class PerplexitySDKError {
        +str message
        +dict details
    }
    class TransportError {
        +int status_code
        +str response_body
    }
    class AuthenticationError {
        401
    }
    class RateLimitError {
        +float retry_after
        429
    }
    class StreamingError
    class ValidationError

    PerplexitySDKError <|-- TransportError
    PerplexitySDKError <|-- StreamingError
    PerplexitySDKError <|-- ValidationError
    TransportError <|-- AuthenticationError
    TransportError <|-- RateLimitError

Retry State Machine

重试状态机

mermaid

stateDiagram-v2
    [*] --> Requesting
    Requesting --> Success: 2xx response
    Requesting --> RetryWait: 429 / 5xx
    Requesting --> Failed: 4xx (non-429)
    RetryWait --> Requesting: backoff elapsed
    RetryWait --> Failed: max_retries exceeded
    Success --> [*]
    Failed --> [*]

mermaid

stateDiagram-v2
    [*] --> Requesting
    Requesting --> Success: 2xx response
    Requesting --> RetryWait: 429 / 5xx
    Requesting --> Failed: 4xx (non-429)
    RetryWait --> Requesting: backoff elapsed
    RetryWait --> Failed: max_retries exceeded
    Success --> [*]
    Failed --> [*]

Step 4: Embed in Documentation

步骤4：嵌入文档

Place diagrams in:

```
README.md
```
— high-level architecture overview
```
docs/architecture.md
```
— detailed component diagrams
Inline in module docstrings — for complex flow explanations
PR descriptions — for explaining changes visually

将图表放置在以下位置：

```
README.md
```
— 高层级架构概览
```
docs/architecture.md
```
— 详细组件图
模块文档字符串中 — 用于复杂流程的解释
PR描述中 — 直观展示变更内容

Diagram Conventions

图表规范

Use consistent colors per layer (Core=blue, Shared=purple, Transport=orange, Domain=green, Client=pink)
Label edges with function/method names when showing call flow
Use subgraphs to group related components
Include error paths in sequence diagrams (alt/opt blocks)
Prefer top-down (
```
TD
```
) for hierarchy, left-right (
```
LR
```
) for flow

为每个层级使用统一颜色（核心层=蓝色，共享层=紫色，传输层=橙色，领域层=绿色，客户端层=粉色）
展示调用流程时，在连线上标注函数/方法名称
使用subgraph对相关组件进行分组
在序列图中包含错误路径（alt/opt块）
层级结构优先使用自上而下（
```
TD
```
），流程优先使用自左至右（
```
LR
```
）

Step 5: Validate Architecture

步骤5：验证架构

After diagramming, verify:

No upward dependencies (lower layers must not import higher layers)
No circular imports between modules
All public APIs are accessible through
```
client.py
```
Exception hierarchy is consistent with
```
core/exceptions.py
```
Transport protocol conformance (
```
core/protocols.py
```
)

完成图表绘制后，验证以下内容：

不存在向上依赖（底层模块不得导入上层模块）
模块之间不存在循环导入
所有公开API均可通过
```
client.py
```
访问
异常层级与
```
core/exceptions.py
```
保持一致
传输层符合
```
core/protocols.py
```
中的协议规范