# g3tfun/pypidownloader architecture

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

- Interactive diagram: https://gitdiagram.com/g3tfun/pypidownloader
- Repository: https://github.com/g3tfun/pypidownloader

## Overview

pypidownloader is a small FastAPI proxy for pip. A client requests a package index, which the API fetches from upstream indexes, rewrites package-file links, and returns; file requests trigger a race among download mirrors and redirect to the winner, with pythonhosted as fallback. Both routes are implemented in api/index.py; internal calls are shown at the handler level because the sampled implementation is a single file.

Main entry points: [`api/index.py`](https://github.com/g3tfun/pypidownloader/blob/main/api/index.py) (Mirror race)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Proxy API"]
  node_index_route["Index handler<br/>[index.py]"]
  node_link_rewrite["Link rewriting<br/>[index.py]"]
  node_index_response["Index response<br/>[index.py]"]
  node_file_route["File handler<br/>[index.py]"]
  node_redirect["File redirect<br/>[index.py]"]
  node_landing["Landing page<br/>[index.py]"]
end

subgraph group_upstream["PyPI Upstreams"]
  node_index_upstreams["Index sources"]
end

subgraph group_downloads["File Downloads"]
  node_mirror_race["Mirror race<br/>[index.py]"]
  node_file_mirrors["File mirrors"]
  node_official_files["Official file host"]
end

node_pip(("pip client"))

node_pip -->|"requests index"| node_index_route
node_index_route -->|"fetches index"| node_index_upstreams
node_index_upstreams -->|"returns content"| node_index_route
node_index_route -->|"rewrites links"| node_link_rewrite
node_link_rewrite -->|"returns content"| node_index_response
node_index_response -->|"serves index"| node_pip
node_pip -->|"requests file"| node_file_route
node_file_route -->|"finds mirror"| node_mirror_race
node_mirror_race -->|"checks files"| node_file_mirrors
node_mirror_race -->|"falls back"| node_official_files
node_mirror_race -->|"returns URL"| node_redirect
node_redirect -->|"redirects"| node_pip
node_pip -->|"opens home"| node_landing

click node_index_route "https://github.com/g3tfun/pypidownloader/blob/main/api/index.py"
click node_link_rewrite "https://github.com/g3tfun/pypidownloader/blob/main/api/index.py"
click node_index_response "https://github.com/g3tfun/pypidownloader/blob/main/api/index.py"
click node_file_route "https://github.com/g3tfun/pypidownloader/blob/main/api/index.py"
click node_mirror_race "https://github.com/g3tfun/pypidownloader/blob/main/api/index.py"
click node_redirect "https://github.com/g3tfun/pypidownloader/blob/main/api/index.py"
click node_landing "https://github.com/g3tfun/pypidownloader/blob/main/api/index.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_index_route,node_link_rewrite,node_index_response,node_file_route,node_redirect,node_landing,node_pip toneBlue
class node_index_upstreams toneAmber
class node_mirror_race,node_file_mirrors,node_official_files toneMint
```

## Components

### Proxy API

- [Index handler](https://github.com/g3tfun/pypidownloader/blob/main/api/index.py): `api/index.py`
- [Link rewriting](https://github.com/g3tfun/pypidownloader/blob/main/api/index.py): `api/index.py`
- [Index response](https://github.com/g3tfun/pypidownloader/blob/main/api/index.py): `api/index.py`
- [File handler](https://github.com/g3tfun/pypidownloader/blob/main/api/index.py): `api/index.py`
- [File redirect](https://github.com/g3tfun/pypidownloader/blob/main/api/index.py): `api/index.py`
- [Landing page](https://github.com/g3tfun/pypidownloader/blob/main/api/index.py): `api/index.py`

### PyPI Upstreams

- **Index sources**

### File Downloads

- [Mirror race](https://github.com/g3tfun/pypidownloader/blob/main/api/index.py): `api/index.py`
- **File mirrors**
- **Official file host**

### Other components

- **pip client**

## Connections

- pip client → Index handler: requests index
- Index handler → Index sources: fetches index
- Index sources → Index handler: returns content
- Index handler → Link rewriting: rewrites links
- Link rewriting → Index response: returns content
- Index response → pip client: serves index
- pip client → File handler: requests file
- File handler → Mirror race: finds mirror
- Mirror race → File mirrors: checks files
- Mirror race → Official file host: falls back
- Mirror race → File redirect: returns URL
- File redirect → pip client: redirects
- pip client → Landing page: opens home