Design documents

Design reference for pplx-cli (pplx-export / pplx-ask) — the deep layer: pipelines, state machines, data contracts, and the Perplexity web API the tool is built against. For task-oriented usage, start with the Guide.

Purpose: system design reference for pplx_export/ (the Perplexity conversation archiving tool). Audience: agents / engineers taking over maintenance. The goal: after reading these documents you can locate the implementation of any mechanism (module/function/line), understand why it is designed this way, and modify it safely.

Division of labor with existing docs (these documents are a superset refinement of them, not a replacement):

• The API reference pages below: field-tested reference for the Perplexity REST/GraphQL API (endpoints / responses / error semantics);
• pplx_export/README.md: tool overview and usage (full pipeline map, conceptual ask sequence);
• The system design pages below: architecture at the module/function/line level — dependencies, pipelines, state machines, data model, rate limiting and error routing.

Line references use the format file.py:NN, all relative to pplx_export/. Every mechanism description in these documents was verified against the source code (2026-07-23, __version__ = "0.1.0", pplx_export/__init__.py:31).

System design

• Architecture overview — layered module map and real import-level dependency graph: how the CLI, command, site, and core layers fit together.
• Export pipeline — the export flow end to end: fetch, raw-first persistence, mode detection, and Markdown rendering.
• Sub-agents and interruptions — deterministic attribution of background sub-agent payloads, and the interruption / resume state semantics of a running export.
• pplx-ask sequence and multi-account switching — the streaming ask sequence in detail and the multi-account cookie switching flow.
• Data model and directory contract — core data models, write boundaries, and the on-disk archive layout every writer must honor.
• Rate limiting and error handling — rate-limit discipline, backoff behavior, and how errors are routed across layers.
• Offline operations — zero-network mechanisms: offline re-render, relations rebuild, and other local maintenance pipelines.
• Testing architecture — the fully offline snapshot-test system: fixtures, regression strategy, and coverage layout.

API reference

• API · authentication model — how the Perplexity web API authenticates: session cookies, tokens, and account identity.
• API · GraphQL — persisted queries / APQ and the GraphQL operations in use.
• API · REST endpoints — field-tested REST endpoints, grouped by purpose.
• API · responses and error semantics — response structure essentials, parsing discipline, and error / risk-control semantics.
• API · discovery methods and roadmap — endpoint discovery via frontend bundle static analysis, and the endpoint improvement roadmap.