--- name: architecture description: 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. context: fork agent: architect --- # 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
PerplexityClient, Conversation"] Domain["domain/
models.py, services"] Transport["transport/
http.py, sse.py"] Shared["shared/
auth.py, logging.py, retry.py"] Core["core/
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: 1. No upward dependencies (lower layers must not import higher layers) 2. No circular imports between modules 3. All public APIs are accessible through `client.py` 4. Exception hierarchy is consistent with `core/exceptions.py` 5. Transport protocol conformance (`core/protocols.py`)

architecture

Scan your own AI components