# jezza34000/py-petkit-api architecture

> Architecture diagram of the GitHub repository jezza34000/py-petkit-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jezza34000/py-petkit-api
- Repository: https://github.com/jezza34000/py-petkit-api

## Overview

PetKit API Client is an asynchronous Python client for managing PetKit accounts and devices. A developer creates `PetKitClient`, retrieves account/device data, then reads device entities or sends commands; media and Bluetooth operations extend that workflow. Device-specific models represent feeders, litter boxes, fountains, and purifiers, while command definitions and shared containers support API operations. The README documents these capabilities; sampled source confirms client requests, command mapping, media processing, and BLE relay behavior, but not every client call path.

Main entry points: [`pypetkitapi/client.py`](https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/client.py) (PetKit client), [`pypetkitapi/media.py`](https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/media.py) (Media manager), [`pypetkitapi/bluetooth.py`](https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/bluetooth.py) (Bluetooth manager), [`pypetkitapi/containers.py`](https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/containers.py) (Account entities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and API"]
  node_client["PetKit client<br/>[client.py]"]
  node_transport["HTTP transport<br/>[client.py]"]
end

subgraph group_devices["Device Data"]
  node_entities["Account entities<br/>[containers.py]"]
  node_feeder["Feeder models"]
  node_litter["Litter models"]
  node_fountain["Fountain models"]
  node_purifier["Purifier models"]
  node_schedules["Schedules"]
end

subgraph group_operations["Device Operations"]
  node_commands["Command mapping<br/>[command.py]"]
  node_bluetooth["Bluetooth manager<br/>[bluetooth.py]"]
end

subgraph group_media["Media"]
  node_media["Media manager<br/>[media.py]"]
  node_mediafiles[("Downloaded media")]
end

node_developer(("Developer"))
node_petkit{{"PetKit API"}}
node_relay{{"PetKit BLE relay"}}

node_developer -->|"creates and calls"| node_client
node_client -->|"makes requests"| node_transport
node_transport -->|"sends API requests"| node_petkit
node_client -->|"builds account data"| node_entities
node_client -->|"parses device data"| node_feeder
node_client -->|"parses device data"| node_litter
node_client -->|"parses device data"| node_fountain
node_client -->|"parses device data"| node_purifier
node_client -->|"uses schedule data"| node_schedules
node_client -->|"maps commands"| node_commands
node_client -->|"exposes BLE control"| node_bluetooth
node_bluetooth -->|"requests relay"| node_transport
node_transport -->|"dispatches BLE requests"| node_relay
node_developer -->|"requests media"| node_media
node_media -->|"requests media data"| node_client
node_media -->|"saves files"| node_mediafiles

click node_client "https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/client.py"
click node_transport "https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/client.py"
click node_commands "https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/command.py"
click node_entities "https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/containers.py"
click node_feeder "https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/feeder_container.py"
click node_litter "https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/litter_container.py"
click node_fountain "https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/water_fountain_container.py"
click node_purifier "https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/purifier_container.py"
click node_schedules "https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/schedule_container.py"
click node_bluetooth "https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/bluetooth.py"
click node_media "https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/media.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_transport toneBlue
class node_entities,node_feeder,node_litter,node_fountain,node_purifier,node_schedules toneAmber
class node_commands,node_bluetooth,node_petkit toneMint
class node_media,node_mediafiles toneRose
class node_developer,node_relay toneIndigo
```

## Components

### Client and API

- [PetKit client](https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/client.py): `pypetkitapi/client.py`
- [HTTP transport](https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/client.py): `pypetkitapi/client.py`

### Device Data

- [Account entities](https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/containers.py): `pypetkitapi/containers.py`
- [Feeder models](https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/feeder_container.py): `pypetkitapi/feeder_container.py`
- [Litter models](https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/litter_container.py): `pypetkitapi/litter_container.py`
- [Fountain models](https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/water_fountain_container.py): `pypetkitapi/water_fountain_container.py`
- [Purifier models](https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/purifier_container.py): `pypetkitapi/purifier_container.py`
- [Schedules](https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/schedule_container.py): `pypetkitapi/schedule_container.py`

### Device Operations

- [Command mapping](https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/command.py): `pypetkitapi/command.py`
- [Bluetooth manager](https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/bluetooth.py): `pypetkitapi/bluetooth.py`

### Media

- [Media manager](https://github.com/jezza34000/py-petkit-api/blob/main/pypetkitapi/media.py): `pypetkitapi/media.py`
- **Downloaded media**

### Other components

- **Developer**
- **PetKit API**
- **PetKit BLE relay**

## Connections

- Developer → PetKit client: creates and calls
- PetKit client → HTTP transport: makes requests
- HTTP transport → PetKit API: sends API requests
- PetKit client → Account entities: builds account data
- PetKit client → Feeder models: parses device data
- PetKit client → Litter models: parses device data
- PetKit client → Fountain models: parses device data
- PetKit client → Purifier models: parses device data
- PetKit client → Schedules: uses schedule data
- PetKit client → Command mapping: maps commands
- PetKit client → Bluetooth manager: exposes BLE control
- Bluetooth manager → HTTP transport: requests relay
- HTTP transport → PetKit BLE relay: dispatches BLE requests
- Developer → Media manager: requests media
- Media manager → PetKit client: requests media data
- Media manager → Downloaded media: saves files