> ## Documentation Index
> Fetch the complete documentation index at: https://faq.exode.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Техническая документация

> Технологический стек, архитектура фронтенда, платформы и работа с GraphQL API — для интеграторов и разработчиков

Этот раздел описывает, как устроена платформа Exode изнутри: на каких технологиях она построена,
как организован фронтенд, какие платформы поддерживаются и как приложение обменивается данными с сервером
через GraphQL. Материал рассчитан на разработчиков и интеграторов, которые подключают внешние сервисы,
пишут кастомный код или работают с API школы.

<Note>
  Для повседневной работы владельцу школы этот раздел не нужен — все настройки доступны в интерфейсе.
  Документация полезна, если вы интегрируете школу с внешними системами (CRM, аналитика, боты) или
  разрабатываете собственные скрипты.
</Note>

## Технологический стек

Клиентское приложение — это single-page application на React с полной типизацией и SSR-серверной частью.

| Технология              | Роль в проекте                                                      |
| ----------------------- | ------------------------------------------------------------------- |
| React + TypeScript      | Основной UI-фреймворк, строгая типизация (`strict: true`)           |
| Apollo Client           | Работа с GraphQL: запросы, мутации, нормализованный кэш             |
| MobX                    | Управление состоянием (сторы по доменам)                            |
| VKUI (`@exode.ru/vkui`) | Основная библиотека UI-компонентов с поддержкой светлой/тёмной темы |
| Material UI             | Отдельные компоненты (таблицы, скелетоны, хлебные крошки)           |
| Tailwind CSS            | Утилитарные классы для вёрстки                                      |
| styled-components       | Сложные стилизованные компоненты                                    |
| Fastify                 | SSR-сервер для отдачи страниц                                       |

## Поддерживаемые платформы

Один и тот же код собирается под несколько платформ. Платформа определяется на этапе сборки и в рантайме.

| Платформа     | Описание                                                                         |
| ------------- | -------------------------------------------------------------------------------- |
| `web`         | Обычное веб-приложение в браузере                                                |
| Android / iOS | Нативные приложения-обёртки (взаимодействуют с вебом через `ReactNativeWebView`) |
| `vk-mini-app` | Приложение внутри VK                                                             |

Определение платформы и окружения выполняется через сторы (`ConfigStore.isDesktop`, `RouterStore.type`)
и компонент `Platform.If`. Продукт также разворачивается в двух режимах — открытый маркетплейс
(`MarketplacePlatform`) и отдельная школа (`SchoolPlatform`).

## Архитектура фронтенда

Код организован по доменам. Ключевые директории:

```
src/
├── components/     UI-компоненты (Atoms, доменные группы, Desktop, Navigation)
├── pages/          Страницы (ленивая загрузка по доменам)
├── modals/         Модальные окна
├── hooks/          Кастомные хуки (core + apollo)
├── store/          Глобальные сторы (core, user, platform, preference)
└── router/         Конфигурация маршрутизации
```

### Как устроены страницы

Все страницы следуют единому шаблону на базе системы компонентов `Page.*`. Типичная страница
разбита на файлы: сам компонент страницы, `index.tsx` (реэкспорт для ленивой загрузки),
`graphql.tsx` (операции), `store.tsx` (стор страницы, если нужен) и папку `views/` с под-компонентами.

```tsx theme={null}
<Page.Wrapper>
    <Page.Head>
        <Page.Header title={t('title')}/>
    </Page.Head>

    <Page.Content>
        <MainContentView/>
    </Page.Content>
</Page.Wrapper>
```

* `Page.Wrapper` — корневой контейнер: восстановление скролла, safe area, тема.
* `Page.Header` / `Page.MainHeader` — заголовок страницы с кнопками действий.
* `Page.Content` → `Page.Row` → `Page.Section` — область контента.
* `Page.Context` — правое контекстное меню (только на десктопе).

### Маршрутизация

Маршрутизация построена на кастомном роутере (`@exode-team/router`). Маршруты описаны в `src/router/routes/`
и поддерживают:

* URL-параметры: `:id`, `:page([0-9]+)`;
* регулярные выражения для валидации;
* типы маршрутов: `tab`, `modal`, `fullscreen`, `iframe`.

Страницы подгружаются лениво через `lazyWithRetry(() => import(...))`. Для навигации используется
компонент `Link` или программный вызов `Router.pushPage(...)`.

### Управление состоянием

Состояние хранится в MobX-сторах, сгруппированных по доменам (`core`, `user`, `platform`, `preference`).
Сторы конкретных страниц лежат рядом со страницей (`pages/**/store.tsx`). Компоненты, читающие сторы,
оборачиваются в `observer()`.

## GraphQL

Взаимодействие с сервером идёт через единый GraphQL-эндпоинт с помощью Apollo Client.

* Схема — источник истины (`schema.gql` в корне проекта).
* Операции описываются в `graphql.tsx` рядом со страницей или доменом.
* Из операций генерируются типизированные хуки (`useXxxQuery`, `useXxxMutation`) командой `yarn graphql:build`.
* Кэш обновляется вручную по паттерну `readQuery` → изменение → `writeQuery` с теми же переменными,
  с синхронным обновлением полей `count`, `items`, `page`/`pages`.

Эндпоинт задаётся переменной окружения `REACT_APP_GRAPHQL_CSR_URL`. Подробнее о внешних запросах,
ключах и авторизации — в разделе [API](/online-schools/developers/api).

<Tip>
  Если вам нужно расширить интерфейс без изменения кода платформы — используйте
  [кастомный код](/online-schools/developers/custom-code), а для реакции на события школы —
  [вебхуки](/online-schools/developers/webhooks).
</Tip>