QALA CODE

Интерактивная карта истории улиц Астаны

Узнай город через историю его улиц.

QALA CODE — образовательный цифровой проект, который превращает карту Астаны в интерактивный путеводитель по истории, культуре, географии и людям, чьи имена и понятия отражены в названиях городских улиц.

Пользователь открывает карту, выбирает улицу и узнаёт, что означает её название, с чем оно связано и почему оно появилось на карте столицы Казахстана.

Главная особенность проекта — собственная структурированная база данных урбанонимов, созданная в рамках исследования. На этой базе работает AI-гид, который позволяет задавать вопросы о названиях улиц естественным языком.

1. Концепция

Обычная карта отвечает на вопрос:

«Где находится улица?»

QALA CODE отвечает на дополнительные вопросы:

«Почему она так называется?»
«Кто или что стоит за этим названием?»
«Как оно связано с историей Казахстана?»
«Какие ещё улицы относятся к этой категории?»

Таким образом, название улицы становится точкой входа в изучение истории и культуры Казахстана.

2. Цели проекта

Основная цель

Создать интерактивную цифровую карту улиц Астаны с информацией об их происхождении и историко-культурном значении.

Дополнительные цели

исследовать названия улиц Астаны;
создать структурированную базу урбанонимов;
классифицировать названия по смысловым категориям;
визуализировать результаты исследования;
создать AI-гид по собственной базе данных;
разработать образовательный QR-квест;
показать взаимосвязь городской среды, истории и цифровых технологий.

3. Целевая аудитория

Основная

школьники;
студенты;
жители Астаны;
учителя истории и обществознания;
туристы.

Дополнительная

исследователи городской среды;
экскурсоводы;
образовательные организации;
родители;
гости столицы.

4. Основные функции

4.1. Интерактивная карта

Главный экран приложения представляет собой карту Астаны.

На карте отображаются исследованные улицы.

Каждая улица имеет:

координаты;
название;
категорию;
ссылку на подробную страницу;
визуальный маркер.

Пользователь должен иметь возможность:

перемещать карту;
изменять масштаб;
искать улицу;
нажимать на улицу;
открывать карточку улицы;
фильтровать улицы по категориям.

5. Карточка улицы

При выборе улицы открывается подробная информация.

Пример:

Улица Абая

Категория:
Личность / литература

Кто это?

Абай Құнанбайұлы — казахский поэт, мыслитель, композитор и просветитель.

Почему улица названа в его честь?

Краткое объяснение происхождения названия.

Историческая справка

Факт №1
Факт №2
Факт №3
Факт №4

Связь с Казахстаном

Краткое описание культурного или исторического значения.

Категория

Личность
Литература

Расположение

Интерактивный фрагмент карты.

QR-код

QR-код ведёт на страницу конкретной улицы.

6. Структура данных улицы

Каждая улица должна храниться в базе данных как отдельная сущность.

Пример:

{
  "id": "street_001",
  "name_ru": "Абая",
  "name_kz": "Абай",
  "slug": "abay",
  "category": "personality",
  "subcategories": [
    "literature"
  ],
  "description": "...",
  "who_is_it": "...",
  "why_named": "...",
  "historical_facts": [
    "...",
    "...",
    "...",
    "..."
  ],
  "cultural_connection": "...",
  "latitude": 51.1282,
  "longitude": 71.4304,
  "sources": [
    {
      "title": "...",
      "url": "..."
    }
  ]
}

7. Категории урбанонимов

Для классификации улиц используется система категорий.

🟦 7.1. Личности

Названия, связанные с конкретными людьми.

Примеры:

Абай;
Қабанбай батыр;
Кенесары хан;
Бауыржан Момышұлы.

Возможные подкатегории:

государственные деятели;
военные;
писатели;
поэты;
учёные;
общественные деятели;
деятели искусства.

🟩 7.2. География Казахстана

Названия географических объектов.

Например:

города;
регионы;
реки;
озёра;
горы;
степи;
исторические территории.

🟨 7.3. История и государственность

Названия, связанные с историческими событиями, государственностью и историческими понятиями.

🟪 7.4. Литература и искусство

Названия, связанные с:

литературными деятелями;
произведениями;
музыкой;
театром;
искусством;
культурными явлениями.

🟧 7.5. Природа

Названия, связанные с:

животными;
растениями;
природными объектами;
ландшафтами;
природными явлениями.

8. Поиск

Пользователь должен иметь возможность искать улицы.

Примеры:

Абая
Қабанбай
Сарыарқа
Кенесары

Поиск должен учитывать:

русское название;
казахское название;
slug;
альтернативные варианты написания.

Например:

Кабанбай
Қабанбай
Qabanbay
Qabanbai

могут вести к одной сущности.

9. Фильтрация

Пользователь может выбрать одну или несколько категорий.

Пример:

☑ Личности
☐ География
☑ История
☐ Литература
☐ Природа

После применения фильтра карта показывает только соответствующие улицы.

10. Карта смыслов Астаны

Отдельный раздел проекта.

Цель

Показать, какие смысловые категории представлены среди исследованных названий улиц.

Например:

Исследовано: 100 улиц

Личности       ███████████████████ 42
География      ███████████         25
История        ████████            18
Литература     █████                10
Природа        ██                    5

Также должна отображаться процентная доля каждой категории.

Важно

Статистика должна сопровождаться количеством исследованных объектов.

Если исследовано только 100 улиц из значительно большего количества, интерфейс должен явно обозначать:

Статистика основана на исследованной выборке из 100 улиц.

11. AI-гид

🤖 AI Guide

Основная AI-функция проекта.

Пользователь может задавать вопросы обычным языком.

Примеры запросов

Почему улица называется Қабанбай батыр?

Кто такой Абай?

Какие улицы названы в честь писателей?

Найди улицы, связанные с историей Казахстана.

Какие названия связаны с природой?

Какие улицы названы в честь исторических личностей?

Покажи улицы, связанные с Астаной.

12. Принцип работы AI

ИИ не должен самостоятельно формировать историческую базу проекта.

Основным источником информации является собственная база QALA CODE.

Архитектура:

Пользователь
     │
     ▼
AI Guide
     │
     ▼
Определение намерения пользователя
     │
     ▼
Поиск по базе QALA CODE
     │
     ▼
Получение релевантных записей
     │
     ▼
LLM
     │
     ▼
Структурированный ответ

13. AI RAG

Для AI-гидa рекомендуется использовать подход RAG.

Retrieval-Augmented Generation

Вместо передачи всей базы данных модели:

пользователь задаёт вопрос;
система определяет, что нужно найти;
выполняется поиск по базе;
находятся релевантные записи;
найденная информация передаётся LLM;
LLM формирует ответ.

Пример:

User:

"Какие улицы названы в честь писателей?"

↓

Query classification:

category = literature
type = personality

↓

Database:

Абай
Мұхтар Әуезов
Сәкен Сейфуллин
...

↓

AI:

В базе QALA CODE найдены следующие улицы...

14. Ограничение AI

AI должен отвечать только на основании доступных данных проекта, когда вопрос требует фактической информации об улицах.

Если информации недостаточно:

«В базе QALA CODE пока нет достаточной информации об этой улице.»

AI не должен придумывать:

исторические факты;
происхождение названия;
даты;
биографии;
источники.

Для каждой фактической записи рекомендуется хранить источники.

15. Источники

Каждая исследованная запись должна иметь список источников.

Пример:

{
  "sources": [
    {
      "title": "Название источника",
      "url": "https://example.com"
    }
  ]
}

Источниками могут быть:

официальные сайты государственных органов;
архивные материалы;
библиотеки;
научные публикации;
энциклопедии;
официальные документы;
авторитетные исторические ресурсы.

16. Страница AI-гидa

Интерфейс:

┌──────────────────────────────────┐
│ 🤖 AI-гид по улицам Астаны       │
│                                  │
│ Спросите меня о названиях улиц   │
│                                  │
│ ┌──────────────────────────────┐ │
│ │ Почему улица называется...   │ │
│ └──────────────────────────────┘ │
│                                  │
│ Популярные вопросы:              │
│                                  │
│ [Улицы в честь писателей]        │
│ [Исторические личности]          │
│ [География Казахстана]           │
│ [Природа]                        │
└──────────────────────────────────┘

17. QR-коды

Для каждой улицы генерируется уникальный QR-код.

Пример:

https://qalacode.kz/street/abay

QR-код размещается:

в интерфейсе приложения;
на печатных материалах;
на карте;
в рамках QR-квеста.

18. QR-квест

«Прогулка по истории Астаны»

Образовательный маршрут из 10 точек.

Каждая точка содержит QR-код.

После сканирования пользователь получает:

информацию об улице;
историческую справку;
вопрос;
варианты ответа или поле для ответа;
переход к следующей точке.

Пример

QR №1

Улица Абая

Вопрос:

Кто такой Абай и какое значение он имеет для культуры Казахстана?

QR №2

Улица Қабанбай батыр

Вопрос:

К какой категории относится название этой улицы?

Ответ:

Историческая личность.

QR №3

Улица Сарыарқа

Вопрос:

С каким географическим понятием связано название улицы?

19. Система прохождения квеста

Пользователь начинает:

START
 ↓
QR #1
 ↓
Ответ
 ↓
QR #2
 ↓
Ответ
 ↓
...
 ↓
QR #10
 ↓
FINISH

В конце отображается:

🎉 Маршрут завершён!

Вы исследовали 10 улиц
и узнали их историческое происхождение.

QALA CODE

20. Главная страница

Главная страница должна содержать:

QALA CODE

Узнай город через историю его улиц.

[Открыть карту]

[🤖 AI-гид]

[Карта смыслов]

[QR-квест]

Дополнительно:

количество исследованных улиц;
количество категорий;
количество исторических личностей;
краткое описание проекта.

21. Страница улицы

URL:

/street/{slug}

Пример:

/street/abay

Страница содержит:

Название
│
├── Категория
├── Кто / что
├── Почему так называется
├── Историческая справка
├── Интересный факт
├── Связь с Казахстаном
├── Карта
├── Источники
└── QR-код

22. API

Backend должен предоставлять API.

Получить список улиц

GET /api/streets

Получить улицу

GET /api/streets/{id}

Поиск

GET /api/streets/search?q=abay

Фильтрация

GET /api/streets?category=personality

Статистика

GET /api/statistics

AI

POST /api/ai/ask

Request:

{
  "question": "Какие улицы названы в честь писателей?"
}

Response:

{
  "answer": "...",
  "streets": [
    {
      "id": "street_001",
      "name": "Абай",
      "slug": "abay"
    }
  ]
}

23. Рекомендуемый стек

Frontend

Next.js
React
TypeScript
MapLibre GL / Leaflet
Tailwind CSS

Backend

Python
FastAPI

Database

PostgreSQL
PostGIS

PostGIS используется для работы с географическими координатами.

AI

LLM API
Embeddings
Vector Search / PostgreSQL pgvector

Для небольшого MVP полноценный vector database может быть необязателен.

Можно начать с PostgreSQL и обычного поиска по структурированным полям.

24. Архитектура

                    ┌─────────────────┐
                    │     USER        │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │    FRONTEND     │
                    │     Next.js     │
                    └────────┬────────┘
                             │
                ┌────────────┼────────────┐
                │            │            │
                ▼            ▼            ▼
             Streets       Search       AI Guide
                │            │            │
                └────────────┼────────────┘
                             ▼
                    ┌─────────────────┐
                    │     FastAPI     │
                    └────────┬────────┘
                             │
                ┌────────────┴────────────┐
                │                         │
                ▼                         ▼
        ┌───────────────┐          ┌──────────────┐
        │  PostgreSQL   │          │      LLM     │
        │    + PostGIS  │          │              │
        └───────────────┘          └──────────────┘

25. Административная часть

Для MVP рекомендуется сделать простую admin-панель.

Администратор может:

добавлять улицу;
редактировать улицу;
удалять улицу;
менять категорию;
добавлять факты;
добавлять источники;
указывать координаты;
публиковать/скрывать улицу.

26. Статусы данных

Каждая запись может иметь статус:

draft
review
published

draft

Информация ещё собирается.

review

Запись подготовлена и ожидает проверки.

published

Запись доступна пользователям и AI-гиду.

Это позволяет отделить исследовательскую работу от опубликованных данных.

27. MVP

Первая версия проекта должна включать:

Обязательно

Необязательно для MVP

28. Этапы разработки

Phase 1 — Исследование

определить критерии отбора улиц;
собрать список улиц;
определить категории;
найти источники;
создать первоначальную базу.

Результат: dataset.

Phase 2 — Backend

создать PostgreSQL;
создать модели;
реализовать CRUD;
создать API;
добавить поиск;
добавить фильтрацию;
реализовать статистику.

Результат: API.

Phase 3 — Frontend

создать карту;
добавить маркеры;
добавить поиск;
добавить фильтры;
создать карточки улиц;
создать страницы улиц.

Результат: интерактивная карта.

Phase 4 — AI

реализовать endpoint /api/ai/ask;
добавить поиск релевантных данных;
подключить LLM;
сформировать prompt;
ограничить ответы данными проекта;
добавить ссылки на улицы в ответы.

Результат: AI-гид.

Phase 5 — QR

создать URL для каждой улицы;
автоматически генерировать QR;
создать QR-квест;
добавить 10 заданий.

Результат: интерактивный образовательный маршрут.

Phase 6 — Analytics

Создать:

количество улиц;
распределение категорий;
карту смыслов;
статистику исследованной выборки.

29. Требования к качеству данных

Каждая опубликованная улица должна иметь минимум:

✓ название
✓ категория
✓ описание
✓ объяснение происхождения названия
✓ минимум 3 факта
✓ источник
✓ координаты

Желательно:

✓ название на казахском
✓ название на русском
✓ интересный факт
✓ культурная связь
✓ фотография
✓ несколько источников

30. UX-принцип

Пользователь не должен чувствовать, что он изучает базу данных.

Взаимодействие должно быть простым:

Увидел улицу
      ↓
Нажал
      ↓
Узнал историю
      ↓
Задал вопрос AI
      ↓
Нашёл похожие улицы
      ↓
Продолжил исследование

31. Образовательная ценность

Проект развивает:

исследовательские навыки;
работу с источниками;
систематизацию информации;
основы баз данных;
картографическую визуализацию;
программирование;
понимание AI и RAG;
критическую работу с информацией.

Особенно важно, что AI является не заменой исследованию, а инструментом работы с результатами исследования.

32. Что создаёт ученик

Ученик самостоятельно создаёт:

1. Dataset

Базу урбанонимов Астаны.

2. Classification

Систему категорий названий.

3. Digital map

Интерактивную карту.

4. AI system

AI-гид, работающий с собственной базой.

5. Educational route

QR-квест по городу.

Таким образом, проект объединяет:

ИССЛЕДОВАНИЕ
      +
DATA
      +
MAP
      +
AI
      +
EDUCATION

33. Критерии готовности

Проект считается готовым к демонстрации, если пользователь может:

открыть карту;
найти улицу;
открыть её карточку;
узнать происхождение названия;
увидеть категорию;
посмотреть источники;
отфильтровать улицы;
задать вопрос AI;
получить ответ на основе базы;
перейти к улице из ответа AI;
отсканировать QR-код;
пройти QR-квест.

34. Сценарий демонстрации

Для защиты рекомендуется следующий сценарий.

Шаг 1

Открыть карту.

«Перед нами обычная карта Астаны, но каждая исследованная улица содержит дополнительный исторический слой.»

Шаг 2

Нажать на улицу Абая.

«Мы можем узнать, кто такой Абай, почему его имя появилось на карте столицы и с чем оно связано.»

Шаг 3

Включить категорию «Личности».

«Теперь карта показывает улицы, названные в честь людей.»

Шаг 4

Открыть «Карту смыслов».

«Мы можем увидеть, какие категории представлены в нашей исследованной базе.»

Шаг 5

Открыть AI-гид.

Спросить:

«Какие улицы Астаны названы в честь писателей?»

ИИ отвечает на основании собственной базы.

Шаг 6

Показать QR-код.

«А теперь цифровую карту можно вынести за пределы компьютера.»

Отсканировать QR-код.

Шаг 7

Показать QR-квест.

«Мы превратили обычную прогулку по Астане в образовательный маршрут.»

35. Финальная идея проекта

QALA CODE показывает, что карта города — это не только дороги и адреса.

За каждым названием может стоять человек, событие, место, природный объект или культурное понятие.

Мы собрали эти истории в собственную базу данных, визуализировали их на карте и создали AI-гид, который позволяет исследовать город с помощью естественного языка.

QALA CODE — это способ читать историю Астаны через названия её улиц.

36. Возможное развитие

В будущем проект можно масштабировать:

QALA CODE
    │
    ├── ASTANA
    │
    ├── ALMATY
    │
    ├── SHYMKENT
    │
    └── другие города Казахстана

В перспективе можно создать единую цифровую базу урбанонимов Казахстана с картами разных городов.

Возможные дополнительные функции:

аудиогид;
маршруты по интересам;
школьные экскурсии;
игровые задания;
достижения;
мультиязычность;
фотографии исторических мест;
временная шкала изменения названий улиц;
сравнение урбанонимов разных городов.

License

Educational / research project.

Name		Name	Last commit message	Last commit date
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
DEVELOPMENT.md		DEVELOPMENT.md
README.md		README.md
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
vitest.config.mts		vitest.config.mts

Latest commit

History

Folders and files

Repository files navigation

QALA CODE

Интерактивная карта истории улиц Астаны

1. Концепция

2. Цели проекта

Основная цель

Дополнительные цели

3. Целевая аудитория

Основная

Дополнительная

4. Основные функции

4.1. Интерактивная карта

Пользователь должен иметь возможность:

5. Карточка улицы

Улица Абая

6. Структура данных улицы

7. Категории урбанонимов

🟦 7.1. Личности

🟩 7.2. География Казахстана

🟨 7.3. История и государственность

🟪 7.4. Литература и искусство

🟧 7.5. Природа

8. Поиск

Примеры:

9. Фильтрация

10. Карта смыслов Астаны

Цель

Важно

11. AI-гид

🤖 AI Guide

Примеры запросов

12. Принцип работы AI

13. AI RAG

Retrieval-Augmented Generation

14. Ограничение AI

15. Источники

16. Страница AI-гидa

17. QR-коды

18. QR-квест

«Прогулка по истории Астаны»

Пример

QR №1

QR №2

QR №3

19. Система прохождения квеста

20. Главная страница

21. Страница улицы

22. API

Получить список улиц

Получить улицу

Поиск

Фильтрация

Статистика

AI

23. Рекомендуемый стек

Frontend

Backend

Database

AI

24. Архитектура

25. Административная часть

26. Статусы данных

draft

review

published

27. MVP

Обязательно

Необязательно для MVP

28. Этапы разработки

Phase 1 — Исследование

Phase 2 — Backend

Phase 3 — Frontend

Phase 4 — AI

Phase 5 — QR

Phase 6 — Analytics

29. Требования к качеству данных

30. UX-принцип