> For the complete documentation index, see [llms.txt](https://vitrina-blogerov.gitbook.io/bloggers-showcase/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vitrina-blogerov.gitbook.io/bloggers-showcase/product-docs/product-docs-en/architecture/storefront-frontend.md).

# Storefront frontend

The storefront frontend is the public interface of the catalog. The client sees it in the browser, in the Telegram mini app on a phone, in Telegram Desktop, and in Telegram Web.

{% hint style="info" %}
The storefront is not a separate frontend application with its own build. It is delivered inside each language version as HTML, CSS, JavaScript, and media files.
{% endhint %}

### Where it is located

The main storefront files are located inside each language version.

<table data-search="false"><thead><tr><th>File or folder</th><th>Purpose</th></tr></thead><tbody><tr><td><mark style="background-color:$info;">templates/base.html</mark></td><td>The main HTML page of the storefront.</td></tr><tr><td><mark style="background-color:$info;">assets/style.css</mark></td><td>Styles, responsiveness, animations, themes, glass effects.</td></tr><tr><td><mark style="background-color:$info;">assets/scrypt.js</mark></td><td>Client-side storefront logic.</td></tr><tr><td><mark style="background-color:$info;">assets/logo.png</mark></td><td>Default logo.</td></tr><tr><td><mark style="background-color:$info;">assets/bg.mp4</mark></td><td>Default video background.</td></tr><tr><td><mark style="background-color:$info;">assets/photos</mark></td><td>Card photos.</td></tr><tr><td><mark style="background-color:$info;">assets/icons</mark></td><td>Icons for tags, platforms, and themes.</td></tr></tbody></table>

After installation, the files are located in the language version folders:

```
/opt/bloggers_platform/apps/ru/
/opt/bloggers_platform/apps/en/
/opt/bloggers_platform/apps/zh/
/opt/bloggers_platform/apps/ar/
```

### How the storefront opens

```mermaid
flowchart TB
    A["User opens the domain"] --> B["Caddy"]
    B --> C["Route /bloggers/{lang}/"]
    C --> D["FastAPI backend of the language version"]
    D --> E["templates/base.html"]
    E --> F["assets/style.css and assets/scrypt.js"]
    F --> G["Requests to /api/bloggers, /api/tags, /api/appearance"]
```

The frontend receives an HTML page from the backend and then requests data through the API of the current language version.

For example, the English storefront uses:

```
https://example.com/bloggers/en/api/bloggers
https://example.com/bloggers/en/api/tags
https://example.com/bloggers/en/api/appearance
```

### What JavaScript does

<details>

<summary>Main storefront logic</summary>

`assets/scrypt.js` is responsible for loading cards, filters, search, sorting, pagination, cart, user profile, opening cards, working with the Telegram WebApp API, and AI search.

It also calculates the current base path so that the same logic works at addresses like:

```
/bloggers/ru/
/bloggers/en/
/bloggers/zh/
/bloggers/ar/
```

</details>

<details>

<summary>Connection with the Telegram mini app</summary>

If the storefront is opened inside Telegram, the frontend calls the Telegram WebApp API: it notifies Telegram that the mini app is ready, expands the window, and uses the Telegram user's data wherever the interface needs it.

</details>

<details>

<summary>Loading the design</summary>

When opened, the storefront requests `/api/appearance`. From this response it gets the logo, video background, color scheme, contact button text, and visual effect settings.

</details>

### What data the storefront receives

| Method                                                           | What it is used for                      |
| ---------------------------------------------------------------- | ---------------------------------------- |
| <mark style="background-color:$info;">GET /api/appearance</mark> | Storefront design.                       |
| <mark style="background-color:$info;">GET /api/tags</mark>       | Filter categories and tags.              |
| <mark style="background-color:$info;">GET /api/bloggers</mark>   | Cards, pagination, filters, and sorting. |
| <mark style="background-color:$info;">POST /api/ai-search</mark> | AI selection of cards.                   |

{% tabs %}
{% tab title="Standard search" %}
The user enters text, selects tags, prices, followers, and sorting. The storefront sends the parameters to `/api/bloggers`, and the backend returns matching cards.
{% endtab %}

{% tab title="AI search" %}
The user writes a query in plain language. The storefront sends it to <mark style="background-color:$info;">/api/ai-search</mark>, receives a list of IDs of suitable cards, and then shows them in the catalog.
{% endtab %}

{% tab title="Cart" %}
Selected cards are stored on the browser side. This is a lightweight client-side cart for further contact with the agency.
{% endtab %}
{% endtabs %}

### Useful

{% hint style="success" %}
The storefront design is changed through the admin panel: logo, video background, color scheme, grain, and contact button. For normal operation, there is no need to edit base.html, style.css, or scrypt.js.
{% endhint %}

{% hint style="warning" %}
If you manually replace files in assets, check the access permissions. The application container does not run as the root user, so the files must be readable and writable by the application.
{% endhint %}

### Not a frontend task

The frontend does not store the card database, does not manage the Telegram token, does not publish posts to the channel, and does not make AI decisions. It only displays the interface and calls the API of the current language version.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://vitrina-blogerov.gitbook.io/bloggers-showcase/product-docs/product-docs-en/architecture/storefront-frontend.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.