Мои проекты

Explore

Создание документации по платформе

Описание каталогов для Backend

chart - разберусь позже

compose - Используется для хранения конфигурационных файлов, связанных с Docker Compose.

Docker Compose - это инструмент для определения и запуска многоконтейнерных Docker-приложений. Он использует YAML-файлы для описания конфигурации приложения, включая определение различных сервисов (контейнеров), их зависимостей, сетевых настроек, томов и других параметров.

Каталог "compose" используется для централизованного хранения всей конфигурационной информации, необходимой для развертывания многоконтейнерного приложения с помощью Docker Compose.

config - Содержит в себе конфигурационные файлы в формате JSON.

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

dist - Содержит в себе скомпиленные файлы конфигурации для билда проекта.

Папка dist (от слова distribution - “распределение”) используется для хранения оптимизированных файлов рабочего сайта.

docs - Хранит всю документацию по коду проекта.

От проекта к проекту содержимое каталога может отличаться, но вот основное содержимое папки docs:

catalogs/ - Содержит файлы с названием всех сущностей в переводе на русский язык.

commands.md - файл, который содержит описание всех команд по бэку.

launch.md - файл, который содержит команды, необходимые для запуска проекта с помощью контейнера.

node_modules - Хранит все установленные в проекте пакеты (библиотеки, фреймворки и другие зависимости), необходимые для работы проекта.

В контексте веб-разработки, каталог node_modules является очень важной частью любого проекта, использующего Node.js и пакетный менеджер, такой как npm или yarn (в нашем случае второй вариант).

Когда мы устанавливаем пакеты в проект с помощью команды yarn add <package>, эти пакеты загружаются и сохраняются в каталоге node_modules.

Рассмотрим основные функции каталога node_modules:

Хранение зависимостей: Все установленные в проекте пакеты, их версии и связи между ними сохраняются в этом каталоге.

Обеспечение доступа к пакетам: Код проекта может импортировать и использовать любые пакеты, находящиеся в node_modules.

Управление версиями: Каждый пакет устанавливается в свою собственную папку внутри node_modules, что позволяет избежать конфликтов версий между пакетами.

Ускорение разработки: Не нужно вручную загружать и управлять каждой зависимостью - пакетный менеджер автоматически устанавливает и обновляет необходимые пакеты.

prisma - Содержит файлы и подкаталоги для работы с базой данных.

Cодержит следующие файлы и подкаталоги:

schema.prisma: Это основной файл конфигурации Prisma, где определяются модели данных, соединения с базой данных и другие настройки.

migrations/: Этот каталог содержит SQL-файлы с миграциями, которые представляют изменения, внесенные в схему базы данных. Миграции позволяют отслеживать и управлять изменениями в структуре базы данных.

src - Основной каталог, содержащий исходный код проекта.

Содержит следующие подкаталоги:

adm - Содержит файлы и подкаталоги, связанные с административными и управленческими компонентами приложения. Вот примерное содержимое папки adm:

authRoutes/: Этот подкаталог и файлы содержащиеся внутри него предназначены для получения информации о текущих логинах пользователя, аутентифицированных в запросе.

config/: В этом подкаталоге содержится файл passport.ts для настройки аутентификации администраторов (admins) в веб-приложении.

graph/: Содержит подкаталог services, в котором определяются типы и резолверы.

services/: В этом каталоге определяются конфигурации для сервиса.

businessTests - Содержит подкаталоги и файлы с тестами.

В разных проектах будут разные тесты, связанные с определенными запросами и сервисами.

cli - Каталог для запуска одноразовых скриптов.

Во всех проектах содержится файл helloCtx.ts, в котором с помощью createContext() создаётся контекст приложения. После чего, он получает доступ к нужному сервису и вызывает различные методы. Запускается скрипт при помощи команд, прописанных в начале файла.

clients

Содержит следующие подкаталоги:

elastic/

kafka/

keycloak/

knex/

queue/

config

decorators - Содержит файл Cacheable.ts, в котором представлена реализация декоратора Cacheable.

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

gen - Содержит файл genGQSchemes.ts, который описывает скрипт для генерации TypeScript-файлов для GraphQL API.

Он использует библиотеку @graphql-codegen/core и несколько плагинов для этой библиотеки, чтобы сгенерировать TypeScript-типы и резолверы на основе существующей GraphQL-схемы.

generated - Содержит сгенерированные Prisma файлы.

graph

Папка graph содержит файлы, связанные с GraphQL-компонентами приложения. Вот стандартное содержимое папки graph:

Файл typeDefs.ts, обеспечивает централизованное управление определениями типов GraphQL, загружая их из различных файлов и объединяя их в единое определение mergedTypeDefs. Это упрощает организацию и использование типов GraphQL в приложении.

Файл resolvers.ts, обеспечивает централизованное управление resolver-функциями GraphQL-API, загружая их из различных файлов и объединяя их в единый объект mergedResolvers. Это упрощает организацию и использование resolver-функций в приложении.

Файл schema.ts, создает единую GraphQL схему, объединяя определения типов (typeDefs) и resolvers (resolvers). Это упрощает управление GraphQL-схемой в приложении, так как все необходимые компоненты объединены в одном месте.

init - Каталог, который хранит в себе проиниченные сущности. рассмотрим следующее содержимое:

Папка common - После того, как мы внесём в meta/addCatalogs.ts предзаполненные поля, с помощью метода .addPredefinedElements и выполним yarn regen создастся файл в этой папке, который будет содержать enum для той сущности, для которой были предзаполнены поля.

Папка elastic - Содержит следующие файлы:

bootstrap.ts - описывает функцию для создания и управления индексами в Elasticsearch (Elasticsearch - это распределенная, высокопроизводительная система поиска и анализа данных). Основная задача этого кода - гарантировать, что все необходимые индексы Elasticsearch созданы и находятся в правильном состоянии. Он позволяет легко управлять индексами, включая удаление и повторное создание при необходимости.

genJobs.ts - В этом файле генерируется объект genJobs, который принимает тип ElasticJobs (экспортируется из файла type.ts) с конфигурациями для различных типов сущностей.

Папка roles - Отвечает за управление ролями и правами доступа пользователей.

В файле initRolesToPermissions.ts определяются наборы разрешений для различных ролей, таких как:

Менеджер (Manager)

Администратор информационной безопасности (InformationSecurityAdmin)

Центр компетенций (CompeetenceCenter)

Поддержка приложений (ApplicationSupport)

Специалист по маркетингу (MarkertingSpecialist)

Fpk

Doss

Grand

Tver

Tyr

А также, формируется массив объектов permissionsOfRole, где каждый объект содержит идентификатор роли и массив идентификаторов разрешений, назначенных этой роли.

Файл initTestManagers.ts - Содержит набор тестовых учетных записей менеджеров с предопределенными ролями (например: менеджер, администратор, комментатор, аналитик и тд.) для тестирования приложения. Это позволяет легко инициализировать необходимые учетные записи пользователей без необходимости создавать их вручную.

integrationClients - Нужно придумать название для этого каталога

В IntegrationClient.ts реализуется класс IntegrationClient, который является оберткой для других методов, обеспечивая дополнительные возможности, такие как отслеживание запросов, обработка ошибок и мониторинг производительности.

В файле hooksTypes.ts определены три интерфейса ClientBeforeRequestArgs, ClientAfterRequestArgs и ClientOnErrorArgs, которые описывают форму данных, передаваемых различным функциям обратного вызова в клиентском приложении. Они используются в качестве типов для аргументов в методах beforeRequest(), afterRequest() и onError() соответственно.

meta - Содержит описание всех сущностей в проекте.

В файле addCatalogs.ts определяется общая структура данных, включая их основные атрибуты (название сущности, её полей и их типов), связи с другими объектами и ограничения на заполнение полей.

В файле addMenu.ts определяется структура меню навигации для проекта. Сначала создаётся новая группа меню с заголовком и иконкой, затем указываются все пункты входящие в это меню.

rest

types - Каталог, содержащий определения енумов TypeScript для различных сущностей в проекте.

utils - Каталог, содержащий вспомогательные функции, константы и другие утилиты.

workers - Содержит файлы, в которых выполняются разные задачи в определенной последовательности для конкретных сущностей.

К примеру, в папке aggregates в файле aggregatesWorker.ts происходит обработка различных фоновых задач, связанных с вычислением и пересчетом различных типов агрегатов, таких как данные о пассажирах, билетах и перевозчиках.

Описание каталогов для Frontend

chart - разберусь позже

dist - разберусь позже

docs - Хранит всю документацию по коду проекта.

commands.md - файл, который содержит описание всех команд по фронту.

configuration.md - файл, который служит для документирования и управления конфигурацией проекта. Он описывает, как проект загружает свои конфигурации из двух источников: файлов конфигурации и переменных окружения.

Ниже будут кратко описаны основные цели этого файла:

Определение источников конфигурации:

Описывается, что конфигурация загружается из файлов default.json и ${ENV}.json, а также из переменных окружения. Переменные окружения имеют приоритет.

Обработка конфигурационных файлов:

Уточняется, как происходит загрузка конфигурации из файлов, включая информацию о том, что если оба файла существуют, они будут объединены, и ${ENV}.json будет иметь приоритет.

Предупреждение о безопасности:

Указано, что файл default.json хранится в системе контроля версий (git), поэтому важно не включать в него секретную информацию (например, пароли и учетные данные базы данных).

Документация переменных конфигурации:

Таблица предоставляет информацию о каждой конфигурационной переменной, включая её ключ, соответствующую переменную окружения, тип, обязательность, значение по умолчанию и назначение.

node_modules - Аналогично каталогу на бэкенде.

В данном каталоге содержатся все установленные пакеты. Если в проекте нет нужных зависимостей, то их можно добавить уже ранее упомянутой командой yarn add <package> и по завершению установки в node_modules добавится папка с названием этого пакета.

public - разберусь позже

src/ - Основной каталог, содержащий исходный код проекта. Может содержать следующие каталоги:

adm

Папка adm содержит файлы и подкаталоги, связанные с административными или управленческими компонентами приложения. Вот содержимое папки adm:

commonActions

functions

pages

После создания новой сущности в мете и выполнения команды yarn regen в этом каталоге автоматически генерируется папка с названием той сущности, которую добавили. А также в ней буду созданы дефолтные папки для:

получения списка (List),

создания новой записи (Create),

для редактирования (Edit),

просмотра (Show).

Например, мы создаём сущность для пользователей (users), для неё у нас будет создана папка users с подпапками UserCreate, UserEdit, UserList и UserShow.

В этих папках будут находиться дефолтные (с пометкой DO NOT EDIT! THIS IS GENERATED FILE) файлы, например DefaultUserCreate.tsx, DefaultUserEdit.tsx, DefaultUserList.tsx и DefaultUserShow.tsx. А также в каждой папке будет находиться файл index.tsx, в котором импортируется дефолтный файл.

Если потребуется изменить какую-либо страницу, то в таком случае создаётся кастомный файл, для этого копируем дефолтный файл и переименовываем с Default в Custom. После чего в файле index.tsx меняем импорт на нужный.

utility

В этом каталоге содержится файл DebugPage.tsx, который предоставляет интерфейс для переключения режима отладки и отображения информации о ролях и разрешениях пользователю. Он позволяет разработчикам легко видеть текущие роли и разрешения.

widgets

Содержит файлы для отображения виджетов на странице

apollo

Этот каталог содержит файлы для настройки и инициализации клиента Apollo, который используется для взаимодействия с GraphQL API. К примеру, в файле getApollo.tsx создаётся клиент Apollo, который будет использоваться для выполнения запросов к GraphQL API, а также происходит обработка ошибок, загрузка файлов и настройка кеширования ответов для оптимизации работы с данными.

authProvider -Каталог, предназначенный для управления аутентификацией и авторизацией пользователей.

config - Каталог, для хранения конфигураций.

Содержит два файла, рассмотрим назначение каждого из них:

config.ts - файл представляет собой функцию getConfig, которая используется для загрузки конфигурации приложения из внешнего JSON-файла (/config.json) и объединения её с переменными окружения. Подробное описание цели этого файла:

Загрузка конфигурации:

Функция отправляет запрос на получение конфигурационного файла (config.json), который содержит настройки приложения, такие как API-эндпоинты, ключи и другие параметры.

Объединение с переменными окружения:

После получения данных из config.json, функция проверяет, есть ли соответствующие переменные окружения. Если они определены (например, VITE_APP_ADMIN_RECAPTCHA_PUBLIC_KEY), то они имеют приоритет и заменяют значения из JSON. Это позволяет легко изменять конфигурацию приложения без необходимости редактирования файла.

Возвращение конфигурации:

Функция возвращает промис, который разрешается в объект, содержащий объединенные конфигурационные параметры. Это позволяет другим частям приложения легко получать доступ к настройкам.

Файл config.ts с функцией getConfig служит для гибкой и безопасной конфигурации приложения, обеспечивая удобный способ загрузки и объединения настроек.

envConfig.ts - файл определяет объект envConfig, который используется для хранения конфигурационных значений, связанных с окружением приложения. Подробное описание цели этого файла:

Определение конфигурации окружения:

Объект envConfig содержит параметры, которые могут изменяться в зависимости от среды, в которой выполняется приложение (например, разработка, тестирование или продакшн).

Хранение переменных окружения:

Поле spaces получает значение из переменной окружения REACT_APP_SPACES. Если переменная не установлена, используется значение по умолчанию — строка '{SPACES}'. Это позволяет разработчикам легко настраивать приложение с помощью переменных окружения.

Гибкость и удобство:

Объект envConfig позволяет централизованно управлять конфигурацией, что упрощает доступ и изменение значений в разных частях приложения.

Файл envConfig.ts с объектом envConfig служит для хранения и управления конфигурационными значениями окружения приложения, обеспечивая гибкость и безопасность в настройках.

contexts - разберусь позже

dataProvider - Каталог, содержащий логику взаимодействия с GraphQL API через клиент Apollo.

В этом каталоге есть файл getCustomMethods.ts, который содержит функцию getCustomMethods. Этот метод принимает экземпляр ApolloClient и возвращает объект с методами для взаимодействия с GraphQL API. Эти методы позволяют выполнять различные операции, такие как запросы и мутации. После чего эти методы можно использовать для различных компонентов.

generated - Каталог, в котором содержатся сгенерированные типы по каждой сущности.

А именно в файле graphql.ts можно найти graphql - схему для каждой сущности и затем применять в сервисах, резолверах и тд.

В файле graphql.schema.json содержится схема GraphQL, которая описывает доступные типы данных и операции в API. Кратко рассмотрим применение:

Валидация данных:

Скалярные типы могут использоваться для валидации входящих данных в запросах и мутациях. Например, если поле ожидает тип Date, API будет проверять, соответствует ли переданная строка формату даты.

Генерация документации:

Описание типов помогает разработчикам и пользователям API понять, какие данные ожидаются и как с ними работать. Это улучшает взаимодействие с API и упрощает его использование.

Инструменты разработки:

Инструменты, такие как GraphQL Playground или Apollo Client, могут использовать эту схему для предоставления автозаполнения и документации в процессе разработки.

hooks

i18n

Папка i18n (internationalization) в проекте содержит файлы, связанные с локализацией и переводом приложения на различные языки.

Типичное содержимое папки i18n включает в себя: два подкаталога en для переводов на английский язык и ru для переводов на русский язык.

Файлы index.ts в папках en и ru в отличии от enCatalogs.ts и ruCatalogs.ts не перегенериваются и в них можно добавлять переводы для различных ошибок и уведомлений не затрагивая изначальную структуру каталогов.

i18nProvider

layout - Каталог, который используется для организации и управления структурой пользовательского интерфейса (UI) приложения.

Вот основное содержимое этого каталога:

AppBar.tsx - содержит компонент для создания верхней панели навигации.

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

Адаптивный интерфейс:

Используется хук useMediaQuery для определения, является ли устройство мобильным (широкий экран ниже определенного размера). Это позволяет динамически изменять содержимое панели в зависимости от размера экрана.

Управление темой:

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

Рендеринг верхней панели:

Компонент RaAppBar (верхняя панель React Admin) используется для отображения панели.

В зависимости от размера экрана, может отображаться либо панель инструментов (ToolBar), либо ничего (для мобильных устройств).

Логотип и навигация:

Внутри панели рендерится логотип (иконка), который является ссылкой на главную страницу (/). Используется компонент Link для навигации.

Гибкость компоновки:

Используются компоненты Box из Material-UI для создания гибкой компоновки, что позволяет легко управлять пространством между элементами.

Layout.tsx - основной файл, который содержит дочерние компоненты в каталоге.

В дальнейшем именно он будет импортироваться в главный файл App.tsx.

Menu.tsx (дефолтный генерируемый файл) и CustomMenu.tsx (используется вместо дефолтного, не генерится) - определяет компонент Menu, который отвечает за отображение бокового меню в приложении на основе React Admin.

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

Управление состоянием бокового меню:

Используется хук useSidebarState для получения состояния (открыто или закрыто) бокового меню.

Получение прав доступа:

Хук usePermissions используется для получения прав доступа пользователя. Это позволяет динамически отображать элементы меню в зависимости от разрешений.

Динамическое создание меню:

menuData формируется путем объединения дополнительных элементов меню, полученных из функции getAdditionalMenu.

Отображение элементов меню:

Если у пользователя есть право доступа к определенному элементу (dashboards.main), отображается элемент DashboardMenuItem.

Затем происходит итерация по menuData, и каждый элемент отображается с помощью компонента MenuItem.

Стилизация и анимация:

Компонент Box используется для стилизации, включая ширину, отступы и анимацию при изменении состояния бокового меню. Анимация реализуется с использованием системы переходов Material-UI.

SubMenu.tsx - отвечает за отображение компонентов подменю.

В этом файле можно изменить отображение пунктов подменю, например, убрать иконки или изменить положение.

themes.ts - содержит компоненты для темной и светлой тем.

В этом файле определяется, то как элементы на страницах будут отображаться (задаются отступы, радиусы скругления, цвета, размеры, шрифты и др.) и анимироваться для каждой темы. Для этого используются классы из библиотеки material-ui.

Colors.tsx - содержит енум для каждого цвета, используемого в проекте.

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

raUiLib

shared

systemHooks

types - нужно ли описывать?

uiLib - Каталог с заготовленными компонентами.

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

utils/ - Каталог, содержащий вспомогательные функции, константы и другие утилиты.

Файл regExps.ts содержит регулярные выражения, которые используются для валидации различных типов входных данных в JavaScript.

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

widgets - Каталог, содержащий компоненты с готовым оформление для разных типов полей.

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

К тому же, все виджеты имеют общий стиль, что придает целостности всему проекту.

*дополнительно (возможно не обязательно)

App.tsx - Корневой компонент приложения.

.gitignore - Файл, указывающий, какие файлы и каталоги должны быть исключены из Git-репозитория.

package.json - Файл, содержащий информацию о проекте и его зависимостях.

tsconfig.json - Файл конфигурации TypeScript, определяющий параметры компиляции.

README.md - Файл, содержащий описание проекта и инструкции по установке и использованию.

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.