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:

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

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

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

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 )