architecture

Original：🇺🇸 English

Translated

Visualize and document pplx-sdk system architecture with Mermaid diagrams — layer maps, data flow, dependency graphs, sequence diagrams, and component relationships. Use when designing new features, onboarding, or documenting how the system works.

1installs

Sourcepv-udpv/pplx-sdk

Added on2026-02-08

NPX Install

npx skill4agent add pv-udpv/pplx-sdk architecture

SKILL.md Content

View Translation Comparison →

Architecture Diagramming & Visualization

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

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

Instructions

Step 1: Identify Diagram Type

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

Step 2: Map the Architecture

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

Step 3: Generate Specific Diagrams

SSE Streaming Sequence

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

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 --> [*]

Step 4: Embed in Documentation

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

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

Step 5: Validate Architecture

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
```
)

architecture

NPX Install

Tags

SKILL.md Content

Architecture Diagramming & Visualization

When to use

Instructions

Step 1: Identify Diagram Type

Step 2: Map the Architecture

Step 3: Generate Specific Diagrams

SSE Streaming Sequence

Exception Hierarchy

Retry State Machine

Step 4: Embed in Documentation

Diagram Conventions

Step 5: Validate Architecture