Architecture reading map¶
Mechanism-level reference for pplx-tools (pplx-export / pplx-ask):
dependencies, pipelines, state machines, data contracts, and reliability
boundaries. For task-oriented usage, start with the User guide.
Scope and source of truth
These pages explain the architecture of pplx_export/ for agents and
engineers maintaining the project. Line references use file.py:NN,
relative to pplx_export/. The descriptions were checked against the
repository on 2026-07-23 (__version__ = "0.1.0",
pplx_export/__init__.py:31); current code and tests remain authoritative.
1. Start with the system map¶
- Architecture overview — layers, module responsibilities, and the import-level dependency graph.
2. Follow a runtime flow¶
- Export pipeline — fetching, raw-response retention, mode detection, and Markdown rendering.
- Sub-agents and interruptions — payload attribution and interruption/resume semantics.
- pplx-ask and accounts — streaming queries and multi-account cookie switching.
3. Understand data and reliability¶
- Data model and directory contract — models, write boundaries, and the on-disk archive contract.
- Rate limiting and error handling — throttling, backoff, terminal states, and error routing.
- Offline operations — zero-network re-render, relation rebuilding, and local maintenance pipelines.
4. Related references¶
- Web API reference — observed REST/GraphQL contracts, response semantics, and discovery notes.
- Maintainer guide — test architecture, contributor workflow, and simulated fixture contracts.