JSON to XML Transformation Platform

Платформа для автоматической генерации Apache Velocity шаблонов для трансформации JSON в XML на основе схем данных.

Описание проекта

Система предназначена для автоматизации процесса создания шаблонов преобразования данных между форматами JSON и XML.

Основная задача: упростить интеграцию с государственными информационными системами (ГИС), которые требуют данные в формате XML, когда исходные данные поступают в JSON.

Что делает платформа:

Парсинг схем - анализирует JSON Schema и XSD схемы
Автоматический маппинг - сопоставляет поля между схемами используя алгоритмы:
- Levenshtein distance (расстояние редактирования)
- Fuzzy matching (нечёткое сопоставление)
- Token sort ratio (сравнение токенов)
Генерация VM шаблонов - создаёт Apache Velocity шаблоны для трансформации
Валидация - проверяет корректность сгенерированных шаблонов
Предпросмотр - показывает результат трансформации на тестовых данных

Архитектура

Система построена на микросервисной архитектуре с 6 основными сервисами:

┌─────────────────────────────────────────────────────────────┐
│                         Frontend                            │
│                    (React + TypeScript)                     │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ↓
┌─────────────────────────────────────────────────────────────┐
│                      NGINX (Reverse Proxy)                  │
│                    Load Balancer + SSL                      │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ↓
┌─────────────────────────────────────────────────────────────┐
│                      BFF Service (API Gateway)              │
│              Оркестрация запросов + Аггрегация              │
└─────┬─────────────┬─────────┬──────────────┬─────────────┬──┘
      │             │         │              │             │
      ↓             ↓         ↓              ↓             ↓
   ┌────────┐ ┌────────┐ ┌────────┐  ┌─────────┐      ┌────────────┐
   │Auth    │ │Projects│ │File    │  │Generator│      │Notification│
   │Service │ │Service │ │Service │  │Service  │      │Service     │
   └─┬──────┘ └─┬──────┘ └─┬──────┘  └─────────┘      └────┬───────┘
     │          │          │                               │
     └──────────┴──────────┴───────────────────────────────┘
                    │                        │
                    ↓                        ↓
           ┌────────────────┐       ┌──────────┐
           │  PostgreSQL    │       │ RabbitMQ │
           │  (Shared DB)   │       │  Queue   │
           └────────────────┘       └──────────┘
                                         │
                                         ↓
                                    ┌──────────────┐
                                    │ email worker │
                                    └──────────────┘

Сервисы

1. Auth Service

Аутентификация и авторизация (JWT)
Управление пользователями и ролями
Регистрация, вход, обновление профиля

Подробнее →

2. BFF Service

API Gateway для фронтенда
Оркестрация запросов между сервисами
Аггрегация данных
Единая точка входа

Подробнее →

3. Projects Service

Управление проектами
Хранение field mappings
История изменений проектов
CRUD операции

Подробнее →

4. Files Service

Загрузка и хранение файлов
Управление JSON/XSD схемами
Тестовые данные и VM шаблоны
Скачивание файлов

Подробнее →

5. Generator Service

Парсинг JSON Schema и XSD
Автоматический маппинг полей
Генерация Apache Velocity шаблонов
Валидация шаблонов
Stateless сервис

Подробнее →

6. Notification Service

Отправка email уведомлений
Асинхронная обработка через RabbitMQ
История уведомлений
Retry механизм

Подробнее →

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

Backend

Language: Python 3.11
Framework: FastAPI
Database: PostgreSQL
ORM: SQLAlchemy
Message Queue: RabbitMQ
Validation: Pydantic
Async: asyncio, httpx, aiofiles
XML/XSD: lxml, xmlschema
JSON: jsonschema, json-ref-dict
Fuzzy Matching: rapidfuzz

Frontend

Framework: React 18
Language: TypeScript
Build Tool: Vite
Styling: Tailwind CSS
State Management: Zustand
HTTP Client: Axios
Desktop: Electron (опционально)

Infrastructure

Reverse Proxy: NGINX
Containerization: Docker + Docker Compose
CI/CD: Docker Compose (dev/prod)
Storage: Local File System (можно заменить на S3/MinIO)

Режимы развертывания

Платформа поддерживает три режима работы в зависимости от ваших требований к инфраструктуре и интеграции:

1. Полностью Web решение (Production)

Файл конфигурации: docker-compose.prod.yml

Полноценное облачное решение с веб-интерфейсом для работы через браузер.

Особенности:

✅ Все компоненты в контейнерах (включая frontend)
✅ NGINX для reverse proxy и load balancing
✅ CloudPub для публичного доступа к приложению
✅ Полная облачная инфраструктура
✅ Email уведомления через RabbitMQ
✅ Автоматический SSL (с настройкой)
✅ Готово для production развертывания

Идеально для:

Публичного доступа к платформе
Командной работы
Enterprise развертывания
Работы из любого браузера

Запуск:

docker-compose -f docker-compose.prod.yml up -d

Доступ:

Web UI: https://your-domain.com (через CloudPub)
API: https://your-domain.com/api

2. Гибрид: Desktop приложение + Облачные сервисы (Development)

Файл конфигурации: docker-compose.dev.yml

Оптимальное решение для разработки - десктоп приложение с облачным хранилищем и функционалом.

Особенности:

✅ Backend сервисы в контейнерах (Docker)
✅ Frontend как desktop приложение (Electron)
✅ Облачное хранилище файлов
✅ RabbitMQ для очередей
✅ Email уведомления
✅ CloudPub для публичного доступа к backend API
✅ Hot reload для разработки

Идеально для:

Разработки и тестирования
Desktop UX с облачными возможностями
Работы с удаленной командой
Доступа к backend API извне

Запуск:

# 1. Запустить backend сервисы
docker-compose -f docker-compose.dev.yml up -d

# 2. Запустить desktop приложение
cd frontend
npm install
npm run dev:electron

Доступ:

Desktop UI: Electron приложение (автоматически откроется)
Backend API: http://localhost:8000 или через CloudPub публичный URL
RabbitMQ UI: http://localhost:15672

3. Полностью локальное решение (Offline)

Файл конфигурации: docker-compose.local.yml

Автономное решение для работы без интернета - все хранится локально.

Особенности:

✅ Минимальный набор сервисов
✅ Desktop приложение (Electron)
✅ Локальное хранилище файлов
✅ Работает БЕЗ интернета (Docker образы в репозитории)
✅ Автоматическая загрузка образов из файлов
✅ Автоматический запуск в dev режиме
❌ Без email уведомлений (нет RabbitMQ)
❌ Без CloudPub (нет публичного доступа)
❌ Без NGINX (прямое подключение к BFF)

Состав сервисов:

PostgreSQL (2 базы данных)
BFF Service (API Gateway)
Files Service (локальное хранилище)
Projects Service
Generator Service

Идеально для:

Работы без интернета
Защищенных/изолированных сред
Личного использования
Максимальной приватности данных
Переносимой установки (флешка/диск)

Подготовка для offline (один раз на машине с интернетом):

# Экспортировать Docker образы в репозиторий
chmod +x export-docker-images.bash
./export-docker-images.bash

# Добавить образы в git и запушить
git add docker-images/
git commit -m "Add Docker images for offline mode"
git push

Запуск (на машине БЕЗ интернета):

# Просто запустите один скрипт - всё автоматически!
chmod +x local.bash
./local.bash

Что происходит при запуске:

✅ Проверка Node.js
✅ Загрузка Docker образов из docker-images/
✅ Проверка Docker
✅ Запуск контейнеров (БЕЗ сборки)
✅ Установка npm зависимостей
✅ Автоматический запуск в dev режиме

Доступ:

Desktop UI: Electron приложение (запустится автоматически)
Backend API: http://localhost:8000 (только локально)

📖 Подробная инструкция: См. OFFLINE-SETUP.md

Сравнительная таблица режимов

Функционал	Production (Web)	Development (Hybrid)	Local (Offline)
Frontend	Web (в контейнере)	Desktop (Electron)	Desktop (Electron)
Backend	Docker	Docker	Docker
Доступ	Публичный URL	Desktop + API URL	Только локально
Хранилище	Облачное	Облачное	Локальное
Email уведомления	✅	✅	❌
Интернет	Обязателен	Обязателен	Не требуется
NGINX	✅	✅	❌
CloudPub	✅	✅	❌
RabbitMQ	✅	✅	❌
Hot reload	❌	✅	✅

Переключение между режимами

# Остановить текущий режим
docker-compose -f docker-compose.<current>.yml down

# Запустить новый режим
docker-compose -f docker-compose.<new>.yml up -d

Важно: Данные БД сохраняются в отдельных volumes для каждого режима, поэтому переключение безопасно.

Быстрый старт

Требования

Docker 20.10+
Docker Compose 2.0+
Node.js 18+ (для фронтенда)
npm или yarn
4GB RAM minimum
10GB свободного места

Development режим (пошаговая инструкция)

Шаг 1: Клонирование репозитория

git clone <repository-url>
cd test

Шаг 2: Запуск Backend сервисов

# Запустить все backend сервисы (PostgreSQL, RabbitMQ, все API)
docker-compose -f docker-compose.dev.yml up -d

# Дождаться пока все контейнеры запустятся (~30 секунд)
# Проверить статус
docker-compose -f docker-compose.dev.yml ps

# Должно быть 8 контейнеров в статусе "Up":
# - postgres-db
# - rabbitmq
# - auth-service
# - bff-service
# - projects-service
# - files-service
# - generator-service
# - notification-service

Проверка работоспособности backend:

# Проверить health check
curl http://localhost:8000/health
# Ожидаемый ответ: {"status":"healthy"}

# Открыть Swagger документацию
open http://localhost:8000/docs

Шаг 3: Запуск Frontend

# Перейти в директорию фронтенда
cd frontend

# Установить зависимости (первый раз)
npm install

# Запустить frontend в режиме разработки
npm run dev

# ИЛИ запустить в режиме Electron desktop приложения
npm run dev:electron

После запуска:

Frontend (web): http://localhost:5173
Frontend (electron): откроется desktop окно

Шаг 4: Создание первого пользователя

# Зарегистрировать пользователя через Swagger UI
# или через curl:
curl -X POST http://localhost:8000/api/auth/create \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "admin123",
    "confirm_password": "admin123"
  }'

Доступы к сервисам

Сервис	URL	Логин/Пароль
Frontend (Web)	http://localhost:5173	-
BFF API	http://localhost:8000	-
Swagger Docs	http://localhost:8000/docs	-
PostgreSQL	localhost:5432	postgres / postgres
RabbitMQ UI	http://localhost:15672	guest / guest

Просмотр логов

# Все сервисы
docker-compose -f docker-compose.dev.yml logs -f

# Конкретный сервис
docker-compose -f docker-compose.dev.yml logs -f bff-service

# Последние 100 строк
docker-compose -f docker-compose.dev.yml logs --tail=100 generator-service

Остановка сервисов

# Остановить backend
docker-compose -f docker-compose.dev.yml down

# Остановить и удалить данные (volumes)
docker-compose -f docker-compose.dev.yml down -v

# Frontend останавливается через Ctrl+C в терминале

Production

# Запустить в production режиме
docker-compose -f docker-compose.prod.yml up -d

Доступы:

Frontend: https://your-domain.com
BFF API: https://your-domain.com/api
Все через NGINX (SSL + Load Balancing)

Основной flow работы

Создание проекта (ONE-SHOT API)

POST /api/projects/full

Один запрос делает всё:

Создаёт проект
Загружает файлы (JSON schema, XSD schema, test data)
Парсит схемы
Автоматически маппит поля
Генерирует VM шаблон
Валидирует шаблон
Сохраняет результаты

Время выполнения: ~5 секунда ⚡

Результат

Вы получаете:

Созданный проект (status: COMPLETED)
3 загруженных файла (JSON, XSD, test_data)
N автоматических маппингов (с confidence score)
Сгенерированный VM шаблон (готов к использованию)
Результаты валидации
Предпросмотр XML (если переданы test_data)

Редактирование (опционально)

Если автоматический маппинг неточный:

Просмотр маппингов: GET /api/projects/{id}/mappings
Обновление: PUT /api/projects/mappings/{id}
Пересоздание шаблона: POST /api/generator/generate

Примеры использования

Простой пример

# 1. Логин
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'

# Response: { "access_token": "eyJ...", ... }

# 2. Создать проект с генерацией (ONE-SHOT!)
curl -X POST http://localhost:8000/api/projects/full \
  -H "Authorization: Bearer eyJ..." \
  -F "name=My Project" \
  -F "description=Test project" \
  -F "files=@json_schema.json" \
  -F "files=@xsd_schema.xsd" \
  -F "files=@test_data.json" \
  -F "file_types=JSON_SCHEMA,XSD_SCHEMA,TEST_DATA" \
  -F "generate=true"

# Response: полный результат с проектом, файлами, маппингами, шаблоном!

# 3. Скачать сгенерированный VM шаблон
curl -X GET http://localhost:8000/api/files/{template_id}/download \
  -H "Authorization: Bearer eyJ..." \
  -o generated_template.vm

Тестовые данные

В директории doc/test/files/ есть готовые примеры:

simple/ - простая схема (5 полей)
medium/ - средняя сложность (15 полей)
complex/ - сложная схема (24+ полей)

API Documentation

После запуска доступна интерактивная документация:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
OpenAPI Schema: http://localhost:8000/openapi.json

Конфигурация

Переменные окружения

Основные настройки находятся в docker-compose.dev.yml / docker-compose.prod.yml

Обязательные:

# Database
DATABASE_URL=postgresql://user:pass@postgres-db:5432/project_db

# JWT
SECRET_KEY=your-secret-key-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# SMTP (для уведомлений)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASSWORD=your-app-password

Опциональные:

# Генератор
DEFAULT_CONFIDENCE_THRESHOLD=0.5
MAX_SCHEMA_SIZE=10485760

# Файлы
MAX_FILE_SIZE=104857600
STORAGE_PATH=/app/storage

Мониторинг и отладка

Проверка здоровья сервисов

# Health check всех сервисов
curl http://localhost:8000/health

# Статус контейнеров
docker-compose -f docker-compose.dev.yml ps

База данных

# Подключиться к PostgreSQL
docker exec -it postgres-db psql -U postgres -d project_db

# Просмотр таблиц
\dt

# Количество проектов
SELECT COUNT(*) FROM projects;

RabbitMQ

Web UI: http://localhost:15672
Login: guest / guest
Просмотр очередей и сообщений

Безопасность

Реализовано:

JWT аутентификация с ограниченным временем жизни
Пароли хешируются с bcrypt
HTTPS в production (через NGINX)
CORS настройки
SQL injection защита (ORM)
Валидация всех входных данных (Pydantic)
Rate limiting (опционально в NGINX)
Изоляция сервисов (Docker network)

Разработка

Структура проекта

project_name/
├── auth-service/          # Аутентификация
├── bff-service/           # API Gateway
├── projects-service/      # Проекты и маппинги
├── files-service/         # Файлы
├── generator-service/     # Генерация VM
├── notification-service/  # Уведомления
├── frontend/              # React UI
├── infrastructure/        # NGINX configs
├── doc/                   # Документация
│   ├── setup/            # Инструкции по настройке
│   ├── test/             # Тестовые данные
│   └── tz/               # Техническое задание
│   └── service/           # Описание сервисов
├── docker-compose.dev.yml
├── docker-compose.prod.yml
└── README.md

Добавление нового сервиса

Создать директорию new-service/
Добавить Dockerfile и requirements.txt
Добавить в docker-compose.dev.yml
Добавить клиента в bff-service/app/services/

Hot reload

В development режиме все сервисы автоматически перезагружаются при изменении кода (volumes mounted).

Roadmap

В разработке:

Улучшение алгоритмов маппинга (ML модель)
Версионирование проектов
Экспорт/импорт проектов
Batch генерация (несколько проектов)
Графический редактор маппингов

Планируется:

Kubernetes deployment
Prometheus + Grafana мониторинг
ELK Stack для логов
S3/MinIO для файлов
Redis для кеширования
CI/CD пайплайн (GitHub Actions)

Итоги

Разработано для автоматизации интеграций с государственными информационными системами.

Технологический стек выбран для:

Высокой производительности (FastAPI + async)
Гибкости и масштабируемости (микросервисы)
Простоты разработки (Python + TypeScript)
Надёжности (Docker + PostgreSQL)

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
auth-service		auth-service
bff-service		bff-service
doc		doc
docker-images		docker-images
files-service		files-service
frontend		frontend
generator-service		generator-service
infrastructure/nginx		infrastructure/nginx
notification-service		notification-service
projects-service		projects-service
websocket-service		websocket-service
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
OFFLINE-SETUP.md		OFFLINE-SETUP.md
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.local.yml		docker-compose.local.yml
docker-compose.prod.yml		docker-compose.prod.yml
export-docker-images.bash		export-docker-images.bash
local.bash		local.bash

Folders and files

Latest commit

History

Repository files navigation

JSON to XML Transformation Platform

Описание проекта

Что делает платформа:

Архитектура

Сервисы

1. Auth Service

2. BFF Service

3. Projects Service

4. Files Service

5. Generator Service

6. Notification Service

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

Backend

Frontend

Infrastructure

Режимы развертывания

1. Полностью Web решение (Production)

2. Гибрид: Desktop приложение + Облачные сервисы (Development)

3. Полностью локальное решение (Offline)

Сравнительная таблица режимов

Переключение между режимами

Быстрый старт

Требования

Development режим (пошаговая инструкция)

Шаг 1: Клонирование репозитория

Шаг 2: Запуск Backend сервисов

Шаг 3: Запуск Frontend

Шаг 4: Создание первого пользователя

Доступы к сервисам

Просмотр логов

Остановка сервисов

Production

Основной flow работы

Создание проекта (ONE-SHOT API)

Результат

Редактирование (опционально)

Примеры использования

Простой пример

Тестовые данные

API Documentation

Конфигурация

Переменные окружения

Мониторинг и отладка

Проверка здоровья сервисов

База данных

RabbitMQ

Безопасность

Реализовано:

Рекомендации для production:

Разработка

Структура проекта

Добавление нового сервиса

Hot reload

Roadmap

В разработке:

Планируется:

Итоги

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages