# mebishp/blinkit-api architecture

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

- Interactive diagram: https://gitdiagram.com/mebishp/blinkit-api
- Repository: https://github.com/mebishp/blinkit-api

## Overview

This is an unofficial, location-aware REST API that turns Blinkit’s web data into product, category, and serviceability responses. The main workflow resolves a caller’s location, checks serviceability, fetches and parses upstream listings, applies local filtering/sorting and pagination, then returns shaped responses; product detail, category discovery, and address lookup are additional domain branches. Edges follow explicit route, catalog, client, and parser references or README statements. Some route and catalog implementations were not excerpted, so unverified calls are omitted.

Main entry points: [`app/services/catalog.py`](https://github.com/mebishp/blinkit-api/blob/main/app/services/catalog.py) (Catalog orchestration), [`app/main.py`](https://github.com/mebishp/blinkit-api/blob/main/app/main.py) (FastAPI app), [`app/blinkit/client.py`](https://github.com/mebishp/blinkit-api/blob/main/app/blinkit/client.py) (HTTP client), [`app/api/routes/products.py`](https://github.com/mebishp/blinkit-api/blob/main/app/api/routes/products.py) (Product routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API boundary"]
  node_app["FastAPI app<br/>[main.py]"]
  node_product_routes["Product routes<br/>[products.py]"]
  node_category_routes["Category routes<br/>[categories.py]"]
  node_location_routes["Location routes<br/>[location.py]"]
  node_health_routes["Health route<br/>[health.py]"]
  node_dependencies["Request dependencies<br/>[deps.py]"]
  node_response_format["Listing responses<br/>[responses.py]"]
end

subgraph group_catalog["Catalog workflows"]
  node_catalog["Catalog orchestration<br/>[catalog.py]"]
  node_listing_cache["TTL cache<br/>[cache.py]"]
  node_query_engine["Listing filters<br/>[query.py]"]
  node_product_detail["Product detail<br/>[catalog.py]"]
  node_category_discovery["Category discovery<br/>[categories.py]"]
  node_location_lookup["Location lookup<br/>[catalog.py]"]
end

subgraph group_upstream["Blinkit integration"]
  node_upstream_client["HTTP client<br/>[client.py]"]
  node_endpoint_map["Endpoint definitions<br/>[endpoints.py]"]
  node_response_parser["Layout parser<br/>[parser.py]"]
end

subgraph group_models["Domain and query"]
  node_schemas["API data models<br/>[schemas.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

node_caller(("API caller"))
node_blinkit["Blinkit services"]

node_caller -->|"sends requests"| node_app
node_app -->|"registers"| node_product_routes
node_app -->|"registers"| node_category_routes
node_app -->|"registers"| node_location_routes
node_app -->|"registers"| node_health_routes
node_app -->|"initializes"| node_catalog
node_app -->|"creates"| node_upstream_client
node_product_routes -->|"uses"| node_dependencies
node_category_routes -->|"uses"| node_dependencies
node_product_routes -->|"requests search and detail"| node_catalog
node_category_routes -->|"requests categories and browse"| node_catalog
node_product_routes -->|"formats listings"| node_response_format
node_category_routes -->|"formats listings"| node_response_format
node_dependencies -->|"resolves location via"| node_catalog
node_dependencies -->|"builds query"| node_query_engine
node_response_format -->|"constructs responses"| node_schemas
node_catalog -->|"caches results"| node_listing_cache
node_catalog -->|"filters listings"| node_query_engine
node_catalog -->|"fetches data"| node_upstream_client
node_catalog -->|"parses upstream data"| node_response_parser
node_catalog -->|"builds category tree"| node_category_discovery
node_catalog -->|"selects paths"| node_endpoint_map
node_upstream_client -->|"uses headers"| node_endpoint_map
node_upstream_client -.->|"requests"| node_blinkit
node_response_parser -->|"creates product models"| node_schemas
node_category_discovery -->|"creates categories"| node_schemas
node_catalog -->|"returns domain data"| node_schemas
node_app -->|"loads configuration"| node_settings
node_upstream_client -->|"configures requests"| node_settings
node_location_routes -.->|"serves location operations"| node_catalog
node_health_routes -.->|"reports health state"| node_catalog
node_catalog -->|"resolves serviceability and addresses"| node_location_lookup
node_location_lookup -->|"queries location endpoints"| node_upstream_client

click node_app "https://github.com/mebishp/blinkit-api/blob/main/app/main.py"
click node_product_routes "https://github.com/mebishp/blinkit-api/blob/main/app/api/routes/products.py"
click node_category_routes "https://github.com/mebishp/blinkit-api/blob/main/app/api/routes/categories.py"
click node_location_routes "https://github.com/mebishp/blinkit-api/blob/main/app/api/routes/location.py"
click node_health_routes "https://github.com/mebishp/blinkit-api/blob/main/app/api/routes/health.py"
click node_dependencies "https://github.com/mebishp/blinkit-api/blob/main/app/api/deps.py"
click node_response_format "https://github.com/mebishp/blinkit-api/blob/main/app/api/responses.py"
click node_catalog "https://github.com/mebishp/blinkit-api/blob/main/app/services/catalog.py"
click node_listing_cache "https://github.com/mebishp/blinkit-api/blob/main/app/services/cache.py"
click node_query_engine "https://github.com/mebishp/blinkit-api/blob/main/app/services/query.py"
click node_product_detail "https://github.com/mebishp/blinkit-api/blob/main/app/services/catalog.py"
click node_category_discovery "https://github.com/mebishp/blinkit-api/blob/main/app/blinkit/categories.py"
click node_location_lookup "https://github.com/mebishp/blinkit-api/blob/main/app/services/catalog.py"
click node_upstream_client "https://github.com/mebishp/blinkit-api/blob/main/app/blinkit/client.py"
click node_endpoint_map "https://github.com/mebishp/blinkit-api/blob/main/app/blinkit/endpoints.py"
click node_response_parser "https://github.com/mebishp/blinkit-api/blob/main/app/blinkit/parser.py"
click node_schemas "https://github.com/mebishp/blinkit-api/blob/main/app/schemas.py"
click node_settings "https://github.com/mebishp/blinkit-api/blob/main/app/config.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_app,node_product_routes,node_category_routes,node_location_routes,node_health_routes,node_dependencies,node_response_format toneBlue
class node_catalog,node_listing_cache,node_query_engine,node_product_detail,node_category_discovery,node_location_lookup toneAmber
class node_upstream_client,node_endpoint_map,node_response_parser,node_caller toneMint
class node_schemas,node_settings toneRose
class node_blinkit toneIndigo
```

## Components

### API boundary

- [FastAPI app](https://github.com/mebishp/blinkit-api/blob/main/app/main.py): `app/main.py`
- [Product routes](https://github.com/mebishp/blinkit-api/blob/main/app/api/routes/products.py): `app/api/routes/products.py`
- [Category routes](https://github.com/mebishp/blinkit-api/blob/main/app/api/routes/categories.py): `app/api/routes/categories.py`
- [Location routes](https://github.com/mebishp/blinkit-api/blob/main/app/api/routes/location.py): `app/api/routes/location.py`
- [Health route](https://github.com/mebishp/blinkit-api/blob/main/app/api/routes/health.py): `app/api/routes/health.py`
- [Request dependencies](https://github.com/mebishp/blinkit-api/blob/main/app/api/deps.py): `app/api/deps.py`
- [Listing responses](https://github.com/mebishp/blinkit-api/blob/main/app/api/responses.py): `app/api/responses.py`

### Catalog workflows

- [Catalog orchestration](https://github.com/mebishp/blinkit-api/blob/main/app/services/catalog.py): `app/services/catalog.py`
- [TTL cache](https://github.com/mebishp/blinkit-api/blob/main/app/services/cache.py): `app/services/cache.py`
- [Listing filters](https://github.com/mebishp/blinkit-api/blob/main/app/services/query.py): `app/services/query.py`
- [Product detail](https://github.com/mebishp/blinkit-api/blob/main/app/services/catalog.py): `app/services/catalog.py`
- [Category discovery](https://github.com/mebishp/blinkit-api/blob/main/app/blinkit/categories.py): `app/blinkit/categories.py`
- [Location lookup](https://github.com/mebishp/blinkit-api/blob/main/app/services/catalog.py): `app/services/catalog.py`

### Blinkit integration

- [HTTP client](https://github.com/mebishp/blinkit-api/blob/main/app/blinkit/client.py): `app/blinkit/client.py`
- [Endpoint definitions](https://github.com/mebishp/blinkit-api/blob/main/app/blinkit/endpoints.py): `app/blinkit/endpoints.py`
- [Layout parser](https://github.com/mebishp/blinkit-api/blob/main/app/blinkit/parser.py): `app/blinkit/parser.py`

### Domain and query

- [API data models](https://github.com/mebishp/blinkit-api/blob/main/app/schemas.py): `app/schemas.py`
- [Runtime settings](https://github.com/mebishp/blinkit-api/blob/main/app/config.py): `app/config.py`

### Other components

- **API caller**
- **Blinkit services**

## Connections

- API caller → FastAPI app: sends requests (evidence: `README.md`)
- FastAPI app → Product routes: registers (evidence: `app/main.py`)
- FastAPI app → Category routes: registers (evidence: `app/main.py`)
- FastAPI app → Location routes: registers (evidence: `app/main.py`)
- FastAPI app → Health route: registers (evidence: `app/main.py`)
- FastAPI app → Catalog orchestration: initializes (evidence: `app/main.py`)
- FastAPI app → HTTP client: creates (evidence: `app/main.py`)
- Product routes → Request dependencies: uses (evidence: `app/api/routes/products.py`)
- Category routes → Request dependencies: uses (evidence: `app/api/routes/categories.py`)
- Product routes → Catalog orchestration: requests search and detail (evidence: `app/api/routes/products.py`)
- Category routes → Catalog orchestration: requests categories and browse (evidence: `app/api/routes/categories.py`)
- Product routes → Listing responses: formats listings (evidence: `app/api/routes/products.py`)
- Category routes → Listing responses: formats listings (evidence: `app/api/routes/categories.py`)
- Request dependencies → Catalog orchestration: resolves location via (evidence: `app/api/deps.py`)
- Request dependencies → Listing filters: builds query (evidence: `app/api/deps.py`)
- Listing responses → API data models: constructs responses (evidence: `app/api/responses.py`)
- Catalog orchestration → TTL cache: caches results (evidence: `app/services/catalog.py`)
- Catalog orchestration → Listing filters: filters listings (evidence: `app/services/catalog.py`)
- Catalog orchestration → HTTP client: fetches data (evidence: `app/services/catalog.py`)
- Catalog orchestration → Layout parser: parses upstream data (evidence: `app/services/catalog.py`)
- Catalog orchestration → Category discovery: builds category tree (evidence: `app/services/catalog.py`)
- Catalog orchestration → Endpoint definitions: selects paths (evidence: `app/services/catalog.py`)
- HTTP client → Endpoint definitions: uses headers (evidence: `app/blinkit/client.py`)
- HTTP client → Blinkit services: requests (evidence: `README.md`)
- Layout parser → API data models: creates product models (evidence: `app/blinkit/parser.py`)
- Category discovery → API data models: creates categories (evidence: `app/blinkit/categories.py`)
- Catalog orchestration → API data models: returns domain data (evidence: `app/services/catalog.py`)
- FastAPI app → Runtime settings: loads configuration (evidence: `app/main.py`)
- HTTP client → Runtime settings: configures requests (evidence: `app/blinkit/client.py`)
- Location routes → Catalog orchestration: serves location operations
- Health route → Catalog orchestration: reports health state
- Catalog orchestration → Location lookup: resolves serviceability and addresses (evidence: `app/services/catalog.py`)
- Location lookup → HTTP client: queries location endpoints (evidence: `app/services/catalog.py`)
