Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
229 lines (178 loc) · 8.61 KB

ARCHITECTURE.md

File metadata and controls

229 lines (178 loc) · 8.61 KB

Architecture Overview

This document serves as a critical, living template designed to equip agents with a rapid and comprehensive understanding of the codebase's architecture, enabling efficient navigation and effective contribution from day one. Update this document as the codebase evolves.

1. Project Structure

This section provides a high-level overview of the project's directory and file structure, categorised by architectural layer or major functional area. It is essential for quickly navigating the codebase, locating relevant files, and understanding the overall organization and separation of concerns.

src/
└── api_pocketcasts/
    ├── __init__.py             # Exposes Client and main exceptions
    ├── client.py               # Main (sync) entry point; thin orchestrator
    # Only synchronous API is supported. Async client was planned but is not implemented.
    ├── exceptions.py           # All custom exceptions
    ├── endpoints/              # One file per *category* (not per endpoint!)
    │   ├── __init__.py
    │   ├── auth.py             # Login, token, user info, user settings, etc.
    │   ├── subscriptions.py    # Podcast subscription, subscribe/unsubscribe, info, episodes
    │   ├── upnext.py           # Up next management
    │   ├── bookmarks.py        # Bookmark management
    │   ├── playlists.py        # Playlist management (new releases, recent, in progress...)
    │   ├── stats.py            # Stat & last played sync
    │   └── discover.py         # Recommendations
    ├── models/                 # Data models, attrs
    │   ├── __init__.py
    │   ├── user.py
    │   ├── podcast.py
    │   ├── episode.py
    │   ├── bookmark.py
    │   ├── playlist.py
    │   ├── stat.py
    │   └── recommendation.py
    └── utils.py                # Shared helpers, http/session logic etc

tests/
├── unit/
│   ├── test_client.py
│   ├── endpoints/
│   │   ├── test_auth.py
│   │   ├── test_bookmarks.py
│   │   ├── test_discover.py
│   │   ├── test_playlists.py
│   │   ├── test_stats.py
│   │   ├── test_podcasts.py
│   │   └── test_upnext.py
│   └── ...
└── integration/
    ├── test_auth_integration.py
    ├── test_podcasts_integration.py
    ├── ...

2. High-Level Architecture

+-------------------------+
|   Consumer Application  |
| (script, backend, bot)  |
+------------+------------+
             |
             v
+-------------------------------+
|  Pocket Casts Python Client   |
| (Sync API surface)             |
|                               |
| client.py                     |
| auth.py                       |
+--------------+----------------+
               |
               v
+----------------------+
| Pocket Casts Servers |
| (Unofficial API)     |
+----------------------+
  • Consumer Application: Imports and uses the library to access Pocket Casts, make API calls, and interact with user/podcast data.
  • Library Core: Python modules implement all API operations, manage authentication, and handle data mapping.
  • Pocket Casts Servers: The library communicates with external Pocket Casts endpoints (REST API) to fetch and mutate data.

3. Core Components

3.1. Python Client API Service

Name: Python Client API Service

Description: Implements all logic to interact with the unofficial Pocket Casts web API, including authentication, data retrieval, and user actions (subscriptions, bookmarks, filters, etc.). Exposes an interface for other Python applications or services to access Pocket Casts functionality programmatically.

Technologies:

  • Python 3.x
  • httpx (sync HTTP client)
  • attrs (data models)

Deployment:
N/A — Distributed as a Python package; runs locally in the end user’s environment.

3.2. Authentication Component

Name: Authentication Component

Description:
Handles all user credentials, login, token refreshing, and securely managing authentication state for API calls.

Technologies:

  • Python 3.x
  • httpx
  • JWT (token handling)

Deployment:
Bundled as part of the main library. No separate deployment.

4. Data Stores

4.1. None

Name: N/A
Type: N/A
Purpose:
No database or persistent storage is included; all data is fetched live from the Pocket Casts service and held in-memory.

Key Schemas/Collections: N/A

Note:
Cachable or persistent data (user settings, podcasts, episodes) are the responsibility of downstream applications if needed.

5. External Integrations / APIs

Service Name: Pocket Casts
Purpose:
Enables access to podcasts, user data, playback history, recommendations, show notes, and more via the unofficial API endpoints.

Integration Method:
REST API (HTTP requests made via Python, using httpx)

6. Deployment & Infrastructure

Cloud Provider: None (local library distribution)
Key Services Used: None
CI/CD Pipeline: GitHub Actions (testing, linting, type-checks)
Monitoring & Logging: None (no server-side code)

7. Security Considerations

Authentication:

  • Supports Pocket Casts authentication using email/password, with tokens (JWTs) obtained via the official login endpoint.
  • Users must provide their credentials directly to the library; credentials are never stored on disk by the library itself.

Authorization:

  • All API requests include an access token (JWT) in the Authorization: Bearer header, enforcing authorization according to Pocket Casts’ server-side rules.

Data Encryption:

  • All API communication is performed over HTTPS (TLS), ensuring data encryption in transit.
  • No local data is persisted, so no encryption at rest is required.

Key Security Tools/Practices:

  • Sensitive values (e.g., email, password, tokens) are maintained only in memory and are cleared upon logout or object destruction.
  • Library users are encouraged to secure their environment variables and configuration files.
  • No web-facing endpoints, so no traditional security appliances/tools required (WAF, DDoS protection, etc.).
  • Regular dependency updates and static analysis via GitHub Actions CI.

8. Development & Testing Environment

Local Setup Instructions:

  • Clone the repository from GitHub.
  • Create and activate a Python virtual environment: 
    python -m venv .venv && source .venv/bin/activate
  • Install dependencies in development mode: 
    pip install -e ".[dev]"
  • (Optionally) review CONTRIBUTING.md for any additional guidelines.

Testing Frameworks:

  • pytest (unit and integration tests)

Code Quality Tools:

  • flake8 (linting)
  • black (formatting)

Additional Notes:

  • Secrets (like Pocket Casts credentials) for testing should be supplied via environment variables (POCKETCASTS_EMAIL, POCKETCASTS_PASSWORD).
  • CI workflows run on GitHub Actions for automated linting and tests on commit and pull request.

9. Limitations and Future Directions

  • Unofficial API: Subject to breakage if Pocket Casts modifies public/internal APIs.
  • No persistent storage, caching, or database layer provided.
  • No web or GUI interface; all usage is programmatic.
  • Only synchronous API is supported.
  • Several endpoints are not yet implemented (see below).
  • Future extensions may include improved error handling, caching options, tracking of API changes, async support, and support for newly discovered endpoints.

Unfinished & Pending Endpoints

The following endpoints are not yet implemented in the library and are planned for future releases:

  • POST /user/bookmark/list
  • POST /user/bookmark/add
  • POST /user/bookmark/delete
  • POST /user/podcast/episode/bookmarks
  • POST /user/podcast/episodes/bookmarks
  • POST /user/stats/add
  • POST /sync/update_episode
  • POST /sync/update_episode_star
  • POST /sync/update_episodes_archive
  • POST /history/do
  • POST /discover/recommend_episodes
  • GET /recommendations/podcast/{podcast_uuid}
  • GET /recommendations/social
  • GET /recommendations/user_podcast

See README.md and reference/endpoints.md for the full list and status.

10. Summary

Pocket Casts Python Client is a modern, developer-centric library for accessing Pocket Casts data and features. With robust sync support, clear model architecture, and streamlined authentication, it enables a wide range of custom podcast workflows in Python applications. Some endpoints are still pending and will be added in future releases.