I have been living in Asia for over two years now, mostly in Vietnam rather than Thailand, and although I haven't become a real guru yet, I have already learned some things and can share them.&#x20;

[https://vietnamguru.ru/](https://vietnamguru.ru/)

vietnamguru.ru

Redesign the video section or remove it altogether.

Very often the coordinates of photos are important, and I specifically enabled geolocation access for the camera.&#x20;

In turn, a single article can contain several entities with their own coordinates at once (not just photos). That is, the system needs to be designed in such a way that it is possible to find the nearest relevant entities specifically taking coordinates into account.&#x20;

Work out the uploading of photos with coordinates, and entities with coordinates in general

For example, on the page [https://vietnamguru.ru/city/thai-nguyen](https://vietnamguru.ru/city/thai-nguyen) there is a link to Hanoi that leads to a non-existent website on the left.

Double-check external links

We are currently getting targeted traffic to the website, but very little interaction. We need to improve the bot's visibility and speed up the initial contact.&#x20;

Increase AI bot chat conversion rate

Set meta tags

Google hasn't added anything new in a month, but yesterday I restored the Map page and it immediately got indexed.&#x20;

![](/images/resized/middle/cmkppub1z0002mu0z427kxsay/1783356959928-image.png)



That means the site is indexing normally. We just need to add some new pages.&#x20;

Boost SEO

Currently, there are almost 1,500 legacy route records in the database. However, the data is stored in a flat structure like this:&#x20;

```json
{
  "id": 4,
  "city": "ho-chi-minh",
  "city2": "mui-ne",
  "time": "07:30",
  "time2": "12:30",
  "price": "120000",
  "company": "Tam Hanh Cafe",
  "type": "bus",
  "gps_link": "https://goo.gl/maps/86122wbjUQ62",
  "gps_link2": "https://goo.gl/maps/1Sabdd9TVy42",
  "address": "199 Phạm Ngũ Lão, Quận 1, Hồ Chí Minh",
  "address2": "135 Nguyễn Đình Chiểu, Phường Hàm Tiến, Thành phố Phan Thiết, Bình Thuận",
  "phone": "+84 283 920 5653",
  "note": ""
}
```

The issue here is that there is no separate reference table, at least for companies.

If we query the companies and transport types with grouping right now, we get the following picture:&#x20;

| count(\*) | company                  | type  |
| --------- | ------------------------ | ----- |
| 772       | Futa Bus                 | bus   |
| 175       | Hanh Cafe                | bus   |
| 41        | Tam Hanh Cafe            | bus   |
| 79        | The Sinh Tourist         | bus   |
| 1         | LC3                      | train |
| 1         | LC4                      | train |
| 1         | MR1                      | train |
| 1         | NH1                      | train |
| 1         | NH2                      | train |
| 34        | SE1                      | train |
| 2         | SE1 (Livitrans Express)  | train |
| 7         | SE1 (Violette Train)     | train |
| 6         | SE17                     | train |
| 8         | SE18                     | train |
| 9         | SE19                     | train |
| 29        | SE2                      | train |
| 2         | SE2 (Livitrans Express)  | train |
| 2         | SE2 (Violette Train)     | train |
| 10        | SE20                     | train |
| 2         | SE21                     | train |
| 2         | SE22                     | train |
| 1         | SE22 (Livitrans Express) | train |
| 35        | SE3                      | train |
| 9         | SE3 (Violette Train)     | train |
| 29        | SE4                      | train |
| 2         | SE4 (Violette Train)     | train |
| 34        | SE5                      | train |
| 29        | SE6                      | train |
| 34        | SE7                      | train |
| 29        | SE8                      | train |
| 1         | SNT1                     | train |
| 1         | SNT2                     | train |
| 1         | SNT2 (Livitrans Express) | train |
| 1         | SP1                      | train |
| 1         | SP2                      | train |
| 1         | SP3                      | train |
| 1         | SP4                      | train |
| 1         | SP7                      | train |
| 1         | SP8                      | train |
| 1         | SPT1                     | train |
| 1         | SPT2                     | train |
| 8         | Boat Company             | boat  |
| 4         | Greenlines DP            | boat  |
| 8         | Ka Long                  | boat  |
| 14        | Phu Quoc Express         | boat  |
| 16        | Superdong                | boat  |
| 10        | The Sinh Tourist         | boat  |



Here, at least SP1, SP2, etc., are not companies at all, but train routes. Meanwhile, SNT2 (Livitrans Express) refers to specific carriage cars operated by Livitrans Express on train SNT2. So the current structure is a complete mess.

However, there is another problem: there are duplicate records.&#x20;

| count(\*) | company       | city        | city2       | time  | address                                               | address2                                              |
| --------- | ------------- | ----------- | ----------- | ----- | ----------------------------------------------------- | ----------------------------------------------------- |
| 4         | Hanh Cafe     | hue         | ho-chi-minh | 08:30 | 28 Chu Văn An, Phú Hội, Thành phố Huế, Thừa Thiên ... | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... |
| 4         | Hanh Cafe     | hue         | ho-chi-minh | 13:30 | 28 Chu Văn An, Phú Hội, Thành phố Huế, Thừa Thiên ... | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... |
| 4         | Hanh Cafe     | hoi-an      | ho-chi-minh | 17:30 | 12 Nguyễn Tất Thành, Phường Cẩm Phổ, tp. Hội An, Q... | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... |
| 2         | Futa Bus      | ho-chi-minh | rach-gia    | 18:15 | 272 Đường Đề Thám, Phường Phạm Ngũ Lão, Quận 1, Hồ... | 260A Nguyễn Bỉnh Khiêm, Vĩnh Thanh, Rạch Giá, tỉnh... |
| 2         | Hanh Cafe     | nha-trang   | ho-chi-minh | 07:30 | 10 Hùng Vương, Lộc Thọ, Thành phố Nha Trang, Khánh... | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... |
| 2         | Hanh Cafe     | nha-trang   | ho-chi-minh | 13:00 | 10 Hùng Vương, Lộc Thọ, Thành phố Nha Trang, Khánh... | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... |
| 2         | Futa Bus      | ho-chi-minh | soc-trang   | 22:00 | 272 Đường Đề Thám, Phường Phạm Ngũ Lão, Quận 1, Hồ... | ấp ngãi hội 2 , thị trấn đại ngãi , huyện long phú... |
| 2         | Hanh Cafe     | phan-thiet  | ha-noi      | 01:30 | 173 Tôn Đức Thắng, Phú Thuỷ, Thành phố Phan Thiết,... | Nguyễn Khoái, Bạch Đằng, Hai Bà Trưng, Hà Nội         |
| 2         | Hanh Cafe     | ho-chi-minh | vinh-long   | 07:45 | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... | Lê Qúy Đôn, Khu 4, Thị Trấn Cái Bè, TT. Cái Bè, Cá... |
| 2         | Hanh Cafe     | phan-thiet  | ha-noi      | 13:30 | 173 Tôn Đức Thắng, Phú Thuỷ, Thành phố Phan Thiết,... | Nguyễn Khoái, Bạch Đằng, Hai Bà Trưng, Hà Nội         |
| 2         | Hanh Cafe     | ho-chi-minh | vinh-long   | 09:30 | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... | Lê Qúy Đôn, Khu 4, Thị Trấn Cái Bè, TT. Cái Bè, Cá... |
| 2         | Futa Bus      | ho-chi-minh | chau-doc    | 07:00 | 272 Đường Đề Thám, Phường Phạm Ngũ Lão, Quận 1, Hồ... | 69 Phan Văn Vàng, Châu Phú A, An Phú, An Giang, Vi... |
| 2         | Hanh Cafe     | ho-chi-minh | vinh-long   | 13:15 | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... | Lê Qúy Đôn, Khu 4, Thị Trấn Cái Bè, TT. Cái Bè, Cá... |
| 2         | Futa Bus      | ho-chi-minh | chau-doc    | 08:00 | 272 Đường Đề Thám, Phường Phạm Ngũ Lão, Quận 1, Hồ... | 69 Phan Văn Vàng, Châu Phú A, An Phú, An Giang, Vi... |
| 2         | Hanh Cafe     | ho-chi-minh | vinh-long   | 16:30 | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... | Lê Qúy Đôn, Khu 4, Thị Trấn Cái Bè, TT. Cái Bè, Cá... |
| 2         | Hanh Cafe     | ho-chi-minh | vinh-long   | 19:15 | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... | Lê Qúy Đôn, Khu 4, Thị Trấn Cái Bè, TT. Cái Bè, Cá... |
| 2         | Futa Bus      | ho-chi-minh | sa-dec      | 16:00 | 272 Đường Đề Thám, Phường Phạm Ngũ Lão, Quận 1, Hồ... | 149/8 khóm Hòa Khánh, Phường 2, Sa Đéc, Đồng Tháp,... |
| 2         | Hanh Cafe     | ho-chi-minh | vinh-long   | 21:30 | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... | Lê Qúy Đôn, Khu 4, Thị Trấn Cái Bè, TT. Cái Bè, Cá... |
| 2         | Futa Bus      | ho-chi-minh | sa-dec      | 17:00 | 272 Đường Đề Thám, Phường Phạm Ngũ Lão, Quận 1, Hồ... | 149/8 khóm Hòa Khánh, Phường 2, Sa Đéc, Đồng Tháp,... |
| 2         | Futa Bus      | ho-chi-minh | chau-doc    | 12:00 | 272 Đường Đề Thám, Phường Phạm Ngũ Lão, Quận 1, Hồ... | 69 Phan Văn Vàng, Châu Phú A, An Phú, An Giang, Vi... |
| 2         | Hanh Cafe     | ho-chi-minh | can-tho     | 07:45 | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... | Mỹ Thuận, Bình Minh, Vinh Long                        |
| 2         | Futa Bus      | ho-chi-minh | sa-dec      | 18:00 | 272 Đường Đề Thám, Phường Phạm Ngũ Lão, Quận 1, Hồ... | 149/8 khóm Hòa Khánh, Phường 2, Sa Đéc, Đồng Tháp,... |
| 2         | Hanh Cafe     | ho-chi-minh | can-tho     | 09:30 | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... | Mỹ Thuận, Bình Minh, Vinh Long                        |
| 2         | Hanh Cafe     | ho-chi-minh | can-tho     | 13:15 | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... | Mỹ Thuận, Bình Minh, Vinh Long                        |
| 2         | Hanh Cafe     | ho-chi-minh | can-tho     | 16:30 | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... | Mỹ Thuận, Bình Minh, Vinh Long                        |
| 2         | Futa Bus      | ho-chi-minh | chau-doc    | 16:00 | 272 Đường Đề Thám, Phường Phạm Ngũ Lão, Quận 1, Hồ... | 69 Phan Văn Vàng, Châu Phú A, An Phú, An Giang, Vi... |
| 2         | Hanh Cafe     | ho-chi-minh | can-tho     | 19:15 | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... | Mỹ Thuận, Bình Minh, Vinh Long                        |
| 2         | Hanh Cafe     | ho-chi-minh | can-tho     | 21:30 | 229 Phạm Ngũ Lão, Phường Phạm Ngũ Lão, Quận 1, Hồ ... | Mỹ Thuận, Bình Minh, Vinh Long                        |
| 2         | Futa Bus      | ho-chi-minh | chau-doc    | 18:00 | 272 Đường Đề Thám, Phường Phạm Ngũ Lão, Quận 1, Hồ... | 69 Phan Văn Vàng, Châu Phú A, An Phú, An Giang, Vi... |
| 1         | Tam Hanh Cafe | mui-ne      | ho-chi-minh | 05:00 | 135 Nguyễn Đình Chiểu, Phường Hàm Tiến, Thành phố ... | 199 Phạm Ngũ Lão, Quận 1, Hồ Chí Minh                 |

We need to get rid of duplicates already at the import stage. Fortunately, there weren't separate pages for each individual route. By the way, we'll need to create them.&#x20;

Refactor the Transport section

Now many images are very small and of poor quality.

Update images

Currently this section is static and not supported by facts. It needs to be reworked into concepts + facts.

![](/images/resized/middle/cmkppub1z0002mu0z427kxsay/1783849641574-image.png)

Redo the FAQ section

Since the relevance of the answers is directly related to understanding where the user is physically located, this data needs to be passed to the AI agent so that it can select the nearest objects rather than just guessing.&#x20;

Pass the user's current coordinates to the AI chat

At a minimum, the following needs to be done:

1\. Make markers non-clickable when selecting route points (route building). Currently, if you click on a marker in this situation, it redirects to the object page.

2\. When building routes, update the URL so that routes can be shared and browser navigation works.

3\. Add filters for geo-objects (islands, cities, tourist spots, etc.).

4\. Expanding the map should not redirect to a separate map page, but should simply render in the document body and be fixed to full screen.

Refine the map

Out of the box, the AI agent only works with its own concepts. Here, we need to teach it to work with all concepts in general. But first, there are many of them, and second, they have structure and logic. We need to add and develop a skill for working with the knowledge base.

There is another point: it is assumed that the AI agent will play a very important role in the website's operation and assist users in every possible way. At the same不过, if you ask it something, it can output a massive wall of useful information, but still just as plain text (albeit formatted). There are no links, no cross-linking, nothing. At the same time, there is really a lot of information. In the current out-of-the-box mechanics, the agent's chat is displayed in a separate widget. If internal page links are displayed in it, then when clicking on them (when the URL changes), the widget automatically collapses. So we need to figure out how—apparently, we will need to turn the chat interface into the main interface for the user: display all internal links within it, and when clicked, they should open as an object card instead of navigating to a page. In general, it needs to be done in such a way that the user can both continue communicating with the agent and view useful information.

Develop the AI agent

Add Contacts page

We need to study what needs to be done on the website to make GEO work better.

By the way, my website is already partially visible in Alice.

![](</images/resized/middle/cmkppub1z0002mu0z427kxsay/1783901685833-Screenshot From 2026-07-13 01-32-53.png>)

Boost GEO (Generative Engine Optimization)

Currently, the website essentially lacks any CTAs, despite having great potential for user scenarios (route planning, at the very least).

We need to add buttons like "Get Directions", "Learn More", etc. to the cards.

Refine CTA and user registration

Currently, the website has mentions of hotels and villas in some older articles, but there is no dedicated section for this.&#x20;

Add "Where to stay" section

Google Analytics, Yandex.Metrica, and similar tools provide a lot of useful information, but:
1\. It is retrospective. That is, you can find out what happened, but you don't really see what is happening right now.
2\. They do not fully tell you how often and which bots visit your site, which pages they view, etc.&#x20;

Now I am going to add new sections and publish a lot of new information. I need to understand how well search engines consume this (how often they visit and where).&#x20;

I recently added [logging for 404 and other errors](https://fi1osof.ru/tasks/cmqiuvvxt000wqq0uh4eptl0c). Now I need to enable logging for all visits in general, so that I can monitor what is happening in real time.&#x20;

Analyze website visits

Right now I have all entities separately (inherited them):&#x20;

* Provinces
* Cities
* Place types (Diving, Waterfall, Pagoda, etc.)
* Places themselves.

This is currently very limited and of little use. We need to figure out which entities to link together, what additional page components to display, and rewrite all the content.

Redesign the website structure, refine it, and rebuild the content

The Map page performs well in search engines and gets good traffic. It makes sense to create separate maps for different provinces and cities to increase the number of targeted landing pages.

Create separate maps for provinces and cities

A new layout has been developed in lovable, we need to redo it.&#x20;

Redesign the website

If a user has built a route on your website, they need a way to actually navigate it in real life. The most valuable features here:

* **Export to .GPX / .KML**: So that the track with all unique points can be loaded in one click into *Maps.me* or *Organic Maps* (the main offline maps for travelers in Vietnam, where the internet frequently drops).
* **Google Maps link generation**: The ability to open the ready-made pool of points directly in the mobile Google app.

Add route exporting

It should be possible to move the object marker to update its data

Add object coordinate editing via drag and drop

It is necessary to add a "What to eat" section and list all the main dishes in it with brief descriptions and photographs. It is advisable to divide it into 3 sections specific to Northern, Southern, and Central Vietnam, and a 4th general one.

Add "What to eat" section

Currently, the coordinates for many cities are inaccurate, and Ha Giang city is even shown somewhere in the territory of China.

Add a resolver for automatic coordinate updates of all geo-objects

There is a separate page with a list of all provinces: [https://vietnamguru.ru/content/reference/aktualniy-spisok-provintsiy-vetnama](https://vietnamguru.ru/content/reference/aktualniy-spisok-provintsiy-vetnama)

Currently, there are several provinces there that are not in our database (pages have not been created for them). We need to add all of them and include links to them.

Along the way, we need to develop a comprehensive province page to display cities, places, etc., within it.

Add missing provinces

It is advisable to be able to show the full map with all provinces and cities at once (their borders)

Draw the borders of individual provinces and cities on the map

Add homestay page

At a minimum, we need:

* Want to visit / Visited
* Like / Dislike, etc.

Directly, the tags will only be visible to the user themselves and their followers. By the way, this can be a great reason to build networks. A user who travels a lot can add their own places, create and share routes, and be active. A follower gets the public experience of a specific person.

We need to work on individual user tags

We need to be able to tell the agent what kind of images are needed, and have it fetch them from somewhere instead of generating them itself.&#x20;

Add image search functionality from external sources to the agent

We have veeeeery many data types and icons in our project. We need to take ComfyUI and generate all the icons (there are hundreds of them).

Generate icons

### Hong Thu's links are mixed up

In Hong Thu's card, the link labeled Booking.com actually leads to Agoda, and the link labeled Tripadvisor leads to Hotwire. This is especially dangerous in a section built on trust and verified information.

Mismatch between the map and the stated ten locations

The map visually marks eight locations:

* Quan Ba;
* Ham Yen;
* Ban Gioc;
* Cao Bang city;
* Ba Be;
* Bac Kan city;
* Lang Son;
* Thai Nguyen.

Meanwhile, the catalog lists ten locations: Bao Lac town and Cửa khẩu Tà Lùng are additional. Because of this, the map currently looks more like an artistic illustration of the network than an accurate representation of the list.

### Grammar

Currently written:

> 24 размещений

Should be:

> **24 размещения**

### Linguistic inconsistency

On the Russian page, the location names look like this:

* Quan Ba town;
* Ham Yen;
* Bao Lac town;
* Ban Gioc waterfall;
* Ba Be lake;
* Cao Bang city.

It is better to choose a uniform format:

> Куанба · Quản Bạ
> Хамйен · Hàm Yên
> Баолак · Bảo Lạc
> Водопад Банзёк · Thác Bản Giốc
> Озеро Ба-Бе · Hồ Ba Bể

This is both helpful for Russian-speaking tourists and preserves the name they can show to a driver or paste into a map.

Fix the Homestays section

There are about 700 old objects in the database. First, they have very simple styling. Second, there is very little content. Third, the coordinates are often incorrect. Fourth, there is no internal linking.&#x20;

Example:

![](/images/resized/middle/cmkppub1z0002mu0z427kxsay/1785182307373-image.png)



We need to improve the templating and system as was done in the Where to stay section.&#x20;

As a result, we should get all these objects with new styling, supplementary information, and internal linking. The cost of a single card should not exceed 3 rubles, meaning the total expenditure should not exceed 2000 rubles (excluding programming costs).

Update old tourist spot cards

Need to add Storybook and different states: read-only and editable.&#x20;

Develop the Route page

There were already some old posts there, but overall they are of very low quality.&#x20;

We now need to implement new post templates and publish at least a couple of posts on various topics every day. It is especially important to break old stereotypes about Vietnam, of which there are very many on the internet. Vietnam may have been the way it is described in the past, but it has changed a lot in recent years.&#x20;

Redesign the Blog section

Develop a separate translation service to and from Vietnamese

# Objective

Develop an independent Vietnamese language learning system for [vietnamguru.ru](https://vietnamguru.ru), primarily focused on an adult Russian-speaking audience and aimed at rapidly building the ability to understand and independently construct living phrases.

## Core Methodological Idea

One cannot mechanically apply the reading acquisition model of a Russian-speaking child to learning a foreign language.

A child learning to read in Russian usually already has two pillars:

* a familiar meaning;
* a familiar sound of the Russian word.

What remains unknown is the written code.

When learning Vietnamese as a Russian-speaking adult, the starting situation is different: the meaning is familiar, but both the Vietnamese sound and its spelling are unknown. Therefore, before the main vocabulary learning begins, the learner needs an initial map of how Vietnamese writing connects to sound.

## Basic Principles of the Course

1. First, provide a compact Vietnamese primer: letters, combinations, the vowel system, syllable structure, diacritics, tones, and basic reading/sound principles.
2. Do not require complete memorization of the primer before continuing the course. Its purpose is to give the adult a map of the system.
3. The primer must always remain at hand as a constant reference tool—for example, a separate tab/bookmark on the right labeled "Primer".
4. After an initial introduction to the system, move on to real words, objects, actions, and situations whose meanings are already clear to the learner.
5. When encountering an unfamiliar symbol, combination, or sound, the learner should easily be able to return to the relevant section of the primer and then back to the word.
6. Learning is structured spirally, not linearly: primer → words → return to primer → new words → phrases → system refinement → spontaneous speech.
7. New words should not become mere flashcards for recognition, but building blocks that are quickly integrated into several different combinations and phrases.

## Why This Matters Specifically for Vietnamese

Vietnamese is analytic and morphologically relatively easy for a Russian-speaking learner, but its phonetic threshold is high: vowel quality, finals, and especially tones are part of the word's lexical form. Therefore, pronunciation cannot be postponed to a later stage. At the same time, there is no need to turn the beginning of the course into an academic lecture on phonology: an adult first needs to be shown a working map of the system and then reinforce it with real words.

## Architectural Model

The main course space should handle:

* familiar meanings and objects;
* sounding Vietnamese words;
* spelling;
* actions and attributes;
* word combinations;
* simple constructions;
* independent spontaneous speech.

The permanent "Primer" should handle the technical map of the language:

* letters and letter combinations;
* vowels and special marks;
* consonants and finals;
* syllable structure;
* tones;
* sound examples;
* pronunciation differences where they are practically significant.

## Adult Learning Principle

The methodology should not be hidden from the user. A separate material should explicitly explain to the adult learner how to use the system: why the primer is initially covered as an overview, why it is normal to return to it dozens of times, why the course is non-linear, and why a word is considered mastered not just after recognition, but after the ability to use it in new combinations.

## Result Criterion

Upon implementation, the user should understand how to start the course, have permanent access to the phonetic map of the language, and gradually transition from recognizing individual words to independently constructing new phrases without first needing to fully master academic grammar.

## Related Tasks

* [Create an interactive Vietnamese primer](https://fi1osof.ru/tasks/cmu84n4160uecqw0q1uqtnuui) — a basic map of sound and writing, permanently accessible.
* [Write the article "How to use the Vietnamese course"](https://fi1osof.ru/tasks/cmu84n41e0ueeqw0qlycksp5u) — an explanation to the adult user of the logic and rules for working with the course.
* [Design learning Vietnamese words through familiar meanings](https://fi1osof.ru/tasks/cmu84n41j0uegqw0qn8ymt23q) — the main learning stream after initial familiarity with the primer.
* [Design the transition from words to phrases and Vietnamese spontaneous speech](https://fi1osof.ru/tasks/cmu84n41p0ueiqw0qu35ypt0j) — transforming familiar words into productive constructions and independent speech.

## Dependency Logic

The primer creates the coordinate system. The article explains to the user how to use it. The word-learning mechanics use the primer as a reference layer. The mechanics of phrases and spontaneous speech are built on top of already mastered words and maintain the ability to return to the primer at any stage.

Design a methodology and learning interface for Vietnamese: an initial primer, learning through familiar meanings, constant returns to phonetics, and transitioning to spontaneous speech.

Develop a Vietnamese language learning system for adult learners

# Objective

Create an interactive Vietnamese primer in [vietnamguru.ru](https://vietnamguru.ru) that users review at the very beginning and then constantly use as a reference map when learning words.

## Role of the Primer

The primer should not be an examination chapter that must be learned perfectly before moving on. Its purpose is to give adults a primary model of how Vietnamese spelling encodes sound, and then remain a tool to return to from specific words.

## What Should Be Inside

* Vietnamese alphabet and special letters;
* `ă`, `â`, `ê`, `ô`, `ơ`, `ư`, `đ` and their pronunciation;
* key consonant and vowel combinations;
* initial consonants and finals;
* basic structure of a Vietnamese syllable;
* six tones as part of a word's sound;
* tone marks and the connection between the mark and the sound;
* practical examples of syllables and words;
* differences between northern/southern pronunciation where they cause real difficulties.

## UX

The primer should be constantly accessible from the main learning interface — for example, as a pinned right-side tab/bookmark "Primer".

It is advisable to provide deep links from a word to a specific fragment of the primer. If a user sees `nước` and doesn't remember `ư`, the final, or the tone, they should be able to open the exact corresponding explanation and then return to the word in a single action.

## Presentation Principle

Do not overload with academic terms and rules for the sake of rules. First show and let the user hear the phenomenon, then briefly explain what they are observing. Sound, tones, and contrasts must be available audibly, not just described in text.

## Result

After the first overview pass, the user is not required to remember everything, but must understand the general mechanics of Vietnamese reading and know where to quickly check any basic element.

## Links

* Parent task: [Develop a Vietnamese language learning system for an adult audience](https://fi1osof.ru/tasks/cmu84may10ueaqw0qkdw49qvz).
* The rules for using the primer must be explained in the task [Write the article "How to use the Vietnamese course"](https://fi1osof.ru/tasks/cmu84n41e0ueeqw0qlycksp5u).
* The primer must be directly integrated into the mechanics of the task [Design the learning of Vietnamese words through familiar meanings](https://fi1osof.ru/tasks/cmu84n41j0uegqw0qn8ymt23q): from a word, the user returns to a specific section of the primer and back.
* Access to phonetics and pronunciation must also be maintained at the level of the task [Design the transition from words to phrases and Vietnamese impromptu speaking](https://fi1osof.ru/tasks/cmu84n41p0ueiqw0qu35ypt0j).

Create a compact, always-accessible map of writing and sounds: letters, combinations, vowels, finals, tones, and syllable structure.

Create an interactive Vietnamese primer

# Objective

Prepare a separate introductory article for an adult audience that immediately explains how to work with the course and dispels the expectation of linear school-style learning.

## What Needs to Be Explained

- why the course starts with an overview primer;
- why the primer does not need to be memorized to perfection;
- why you need to return to it while learning words;
- why going back is a normal learning mechanism, not a mistake;
- why the course is intentionally built in a spiral structure;
- why pronunciation and tones cannot be postponed "for later";
- why it is not required to learn all the grammar first;
- why learning must quickly transition from recognizing a word to using it;
- why it is helpful for adults to understand the methodology itself, rather than just doing exercises.

## Key Formula

First go through the sound and writing map → move on to meaningful words → return to the primer when necessary → connect words into constructions → use known elements for independent new phrases.

## Behavioral Examples

Show specific scenarios:

- saw `nước`, not sure about `ư` → opened the primer → checked → returned;
- confuses two tones → opened the comparison → listened → returned to the words again;
- learned `uống` → does not stop at the flashcard, but uses it in `uống nước`, `uống cà phê`, `muốn uống`, questions, and negations.

## Article Tone

Talk to adults as adults: explain the logic and provide tools for self-control. Do not turn the material into an academic manual or promise magical learning without effort.

## Result

After reading the article, the user understands exactly what to do at the start and how to use the course going forward without feeling like they are "learning wrong" when returning to previously covered reference materials.

## Connections

- Parent task and general methodology: [Develop a Vietnamese language learning system for an adult audience](https://fi1osof.ru/tasks/cmu84may10ueaqw0qkdw49qvz).
- The article must explicitly direct the user to the permanently available tool from the task [Create an interactive Vietnamese alphabet primer](https://fi1osof.ru/tasks/cmu84n4160uecqw0q1uqtnuui).
- The scenario "meaning → word → sound → spelling → return to the primer" is taken from the task [Design the study of Vietnamese words through familiar meanings](https://fi1osof.ru/tasks/cmu84n41j0uegqw0qn8ymt23q).
- The explanation of the criterion for real word acquisition and transition into independent speech must align with the task [Design the transition from words to phrases and Vietnamese impromptu speaking](https://fi1osof.ru/tasks/cmu84n41p0ueiqw0qu35ypt0j).

Explain the course methodology, the role of the primer, non-linear returns, and the criterion for true vocabulary acquisition to an adult audience.

Write the article "How to Use the Vietnamese Course"

# Objective

Design the main format for introducing an adult Russian-speaking user to new Vietnamese vocabulary after completing the initial primer.

## Initial Model

Unlike a child learning to read in their native language, a foreign learner knows the meaning, but knows neither the Vietnamese pronunciation nor its spelling. Therefore, the familiar meaning must serve as an anchor point, while pronunciation and spelling act as newly linked representations.

## Basic Word Scenario

1. Present a familiar meaning: an object, action, attribute, or situation.
2. Provide the correct full Vietnamese pronunciation, including the tone.
3. Show the spelling.
4. Allow breaking down the spelling using the already familiar primer map.
5. Re-link the meaning, sound, and spelling into a single entity.
6. Quickly use the word in several contexts.

## What Matters

- do not introduce a word as an abstract pair "Vietnamese spelling = Russian translation";
- tone and sound quality are part of the word itself from the very first encounter;
- audio must be a first-class interface element;
- a transition to the corresponding section of the primer must be available from the word;
- prioritize highly combinable words: basic actions, questions, negation, desires, location, and frequent objects;
- whenever possible, present objects and actions through visually/situationally clear meanings rather than long Russian definitions.

## Spiral Reinforcement

The same phonetic or orthographic phenomenon must appear in different words. The user gradually learns the pattern through real-life examples, and the primer helps clarify it when needed.

## Result

We need to obtain a repeatable learning unit template suitable for words, objects, actions, and attributes, which can be scaled to a large dictionary without turning the course into a set of rote-memorization flashcards.

## Connections

- Parent task: [Develop a Vietnamese language learning system for an adult audience](https://fi1osof.ru/tasks/cmu84may10ueaqw0qkdw49qvz).
- Preliminary support for analyzing pronunciation and spelling: [Create an interactive Vietnamese language primer](https://fi1osof.ru/tasks/cmu84n4160uecqw0q1uqtnuui).
- User scenario and explanation of non-linear course navigation must be described in the article [How to use the Vietnamese course](https://fi1osof.ru/tasks/cmu84n41e0ueeqw0qlycksp5u).
- The result of this task serves as input for the task [Design the transition from words to phrases and Vietnamese impromptu speech](https://fi1osof.ru/tasks/cmu84n41p0ueiqw0qu35ypt0j): mastered words must be passed on as building blocks rather than completed flashcards.

Develop the main learning flow: familiar object/action → pronunciation → spelling → breakdown via the primer → reinforcement.

Design learning Vietnamese words through familiar meanings

# Objective

Design the next level of the course after individual words: transforming familiar vocabulary into productive structures and early independent improvisation.

## Main Criterion

A word cannot be considered fully mastered just because the user recognizes it on a flashcard. It must start working as a building block for new utterances.

## Method

Build a family of combinations from each new high-frequency word, gradually changing one element while keeping the familiar structure.

Example for `uống`:

- `uống nước`;
- `uống cà phê`;
- `muốn uống`;
- negation with `uống`;
- question with `uống`;
- substitution of various subjects and objects.

The user should see not a list of ready-made phrases, but a transformation space: what exactly can be replaced and what new meaning will result.

## First Constructive Models

Develop a set of the most productive initial patterns, for example:

- subject + action + object;
- negation;
- desire;
- presence/absence;
- question `có ... không?`;
- questions `gì`, `ai`, `đâu`, `bao nhiêu`, etc.;
- object + attribute;
- basic temporal/aspectual markers as needed.

The formal list should be refined at the design stage, focusing not on grammatical completeness, but on combinatorial value for living speech.

## Improvisation

Exercises should gradually remove the ready-made phrase and leave a semantic task. The user assembles an utterance from already familiar elements and then transfers the same structure to a new situation.

It is important to avoid constant full translation of a Russian sentence into Vietnamese. The goal is to establish the route "situation/meaning → familiar Vietnamese structure".

## Connection to the Primer

Even at this stage, pronunciation remains part of the learning process: from any word in a phrase, one can return to its sound and further to a specific element of the primer.

## Result

Obtain a system of exercises and interface patterns where the user, even with a small vocabulary, is able to independently create many new correct or nearly correct utterances, rather than just repeating memorized phrases.

## Links

- Parent task and general methodology: [Develop a Vietnamese language learning system for an adult audience](https://fi1osof.ru/tasks/cmu84may10ueaqw0qkdw49qvz).
- The main input for this task is the result of the task [Design the learning of Vietnamese words through familiar meanings](https://fi1osof.ru/tasks/cmu84n41j0uegqw0qn8ymt23q): familiar vocabulary should arrive here already connected with meaning, sound, and spelling.
- In case of phonetic difficulties at the phrase level, the user should have a direct return to the system from the task [Make an interactive Vietnamese language primer](https://fi1osof.ru/tasks/cmu84n4160uecqw0q1uqtnuui).
- The introductory article [How to use the Vietnamese course](https://fi1osof.ru/tasks/cmu84n41e0ueeqw0qlycksp5u) should explain to the user in advance that the goal of the course is not the accumulation of flashcards, but the transition to independent combination of known elements.

Create mechanics where familiar words become building blocks for structures, allowing the user to start creating new phrases early on.

Design the transition from words to phrases and Vietnamese improvisation

# Context

Initial research showed that relying on the browser's `speechSynthesis` for the Vietnamese language is not feasible.

## Why browser speechSynthesis is unsuitable

- The voice for Vietnamese cannot be reliably set in the browser.
- The available installation path via Reading Mode is inconvenient for a regular user: open reading mode → settings → languages → add Vietnamese → wait for voices to download.
- In practice, after enabling Vietnamese, a `Downloading voices ...` message appears, after which the download may hang indefinitely.
- Official documentation does not provide a transparent guarantee of support for a specific Vietnamese voice.
- In Chromium sources, the language may be declared, but Chromium itself does not contain the final voice dictionaries: voice availability and quality depend on the specific browser/service provider, in our case Google.
- Even if the voice is available to the developer, users cannot be required to install additional system or browser dictionaries just to use the course.

## Second issue: Quality

The developer is not a native Vietnamese speaker and cannot independently guarantee phonetic correctness, tone naturalness, and synthesis quality. Therefore, a controlled generation pipeline followed by verification by a native speaker is needed.

# Solution

Implement a custom text-to-speech pipeline via **OpenRouter + Google Gemini**.

Do not generate audio on every user request. Instead, create a persistent audio dictionary.

## Base Model

1. An entity/dictionary of units for audio appears in the system: letter, syllable, word, phrase, or other learning element.
2. For missing audio, generation is triggered via OpenRouter + Google Gemini.
3. The resulting audio file is saved to file storage.
4. Metadata and the connection to the learning unit are saved in the database.
5. Subsequent requests use the already saved file.
6. There must be a way to re-generate specific audio without changing the learning unit itself.
7. A native speaker later checks the quality and marks suitable/unsuitable options.

## Things to Consider

- structure of the audio entity in the database;
- types of voiced objects: letter, sound, syllable, word, phrase;
- storage of source text and generation parameters;
- provider/model and model version;
- format and storage location of audio files;
- caching and reuse;
- statuses: generated / needs review / confirmed by native speaker / rejected;
- re-generation and versioning;
- differences between Northern and Southern pronunciation, if multiple voice options are needed;
- bulk generation for the primer and dictionary;
- ability to manually upload a native speaker's reference recording;
- quality review interface.

## First Practical Stage

First, provide high-quality audio for the primer:

- basic vowels;
- consonants and combinations;
- six tones on the same/comparable syllable;
- main diphthongs and triphthongs;
- word examples.

After quality confirmation, expand the same mechanism to the entire course dictionary.

## Result Criterion

The user receives audio without installing any system voices or dictionaries. The same learning element is played from pre-generated and saved audio, and the quality can be independently checked and confirmed by a native speaker.

Eliminate the dependency on browser speechSynthesis for Vietnamese and implement managed generation, verification, and storage of audio using OpenRouter + Google Gemini.

Develop a custom Vietnamese text-to-speech pipeline and audio dictionary

# Context

The basic TTS mechanics via OpenRouter are already implemented, but a technical issue has been discovered: when sending a single letter for voice generation, OpenRouter returns an HTTP 400 error.

This is critical for the primer, as high-quality audio generation of individual letters, sounds, and short phonetic units is required.

# Objective

Research and implement an alternative local TTS pipeline via a local server that can stably generate audio for single letters and other minimal units of the Vietnamese language without OpenRouter limitations.

## What needs to be tested

- which local TTS models support the Vietnamese language;
- whether they can correctly synthesize single letters, syllables, and very short strings;
- the quality of tones and phonetics;
- the feasibility of running the model on a local server;
- the API for calls from vietnamguru.ru;
- audio formats and generation latency;
- hardware requirements;
- licenses and usage restrictions;
- the possibility of batch generation of the voiceover dictionary;
- compatibility with the existing audio file and metadata storage system.

## Proposed Architecture

vietnamguru.ru → local TTS API → local model → audio file → existing voiceover dictionary/storage.

The local mechanism should be treated as a source audio generator; generated recordings, just like in the main TTS pipeline, should be saved and reused rather than synthesized on every playback.

## Acceptance Criteria

Find and verify a local generation method that stably accepts single letters and short phonetic elements of the Vietnamese language and produces sound of sufficient quality for further verification by a native speaker.

Bypass the OpenRouter limitation when generating audio for single letters and test a local TTS pipeline for the Vietnamese language via a dedicated server.