Tukuk-OSWhen you open the Images tab in Tukuk-OS and watch a grid of pictures appear, a fairly interesting chain of requests is happening behind it. This article opens that black box — how pictures and videos are searched, extracted, and served quickly.
There Is No Image Index of Our Own (And Why)
Unlike text search, which uses our own Meilisearch index, image and video search runs live (on demand) when you click the tab. That means results are always fresh, but it also means we depend on external providers to respond.
This choice was made because indexing millions of images ourselves would require storage, bandwidth, and licensing that are unrealistic for a personal project. By requesting results live, Tukuk-OS brings fresh data without permanently storing other people's content.
The Request Flow for Images
When you open the Images tab the browser sends GET /images?q=...&page=1:
- The server normalises the query (trim, clean, cap length).
- If a cache entry exists for that query and page it is returned instantly.
- Otherwise the server sends a request to the image provider with normal browser headers (so a plain HTML response is accepted).
- The HTML response is parsed: each result carries a main image, a thumbnail, a title, and a source link.
- Invalid results (no image URL, or only a default logo) are discarded before being sent to you.
Step 4 matters. At one point a broken response from the provider filled the grid with the same image repeated over and over. After I added that validation the grid stays clean even when a source sends partial data.
Pagination
The first page returns about thirty-five images. When you scroll down and click "load more", the server calls the same source with a new page parameter — the offset changes, and new images are appended to the grid without removing the existing ones.
The cache key includes the page number, so page 1 and page 2 never mix. Weak results (fewer than a handful of valid hits) are not cached at all, because a cache poisoned with broken data would ruin every subsequent search for that query.
The Request Flow for Videos
Videos are fetched from YouTube with a different approach: the server requests the YouTube search page, then locates an embedded JSON data block in the HTML (rather than scraping HTML nodes raw). That block contains video information in a tree structure.
The server then walks the tree and extracts: video title, URL, thumbnail, channel name, duration, and view counts. Joining that metadata ensures every video card shows "channel · views · duration" without duplicated information.
YouTube also returns a continuation token for the next batch of results. The token is stored alongside the results and sent back when you click "load more", enabling a seamless continuation without regenerating the search query.
Respecting Content Creators
Image search has a serious ethics issue: most pictures on the internet have creators, and search engines have a responsibility not to steal them. Tukuk-OS's approach is to be a conduit, not a vault: we show a preview, but the primary link takes you to the original page where the image was published.
We do not store copies of images in our own storage — previews are fetched from the source every time they are displayed. This means creators still get visits and traffic when you click, and we do not become an unlawful archive of other people's work.
For video the principle is the same: results show title, channel, and duration, but links take you to the original platform where the creator earns the view. We also avoid extracting or storing the video file itself — all we carry is information to help you find it.
These simple rules may seem like limiting the product, but they actually protect us and make results more useful: you always know where the true source lives, and you can always go there for full context, credit, and information.
Handling Failures Gracefully
When an external provider fails (network issues, blocking, or their own errors) the endpoint returns an empty list with an honest error message, not a confusing error page. The UI then shows a "no results" message and retries when you click the provided button.
Failure states are never cached — only successful results. This prevents a temporary failure from becoming the "official answer" for that query.
Honest Limitations
Because we rely on external sources, some queries may return different results from time to time, and some regions may be blocked by the provider. Tukuk-OS does not promise universal coverage — it promises that when results are shown they are valid, come from honest sources, and can be traced back to the original page.