Veevvo Developer Documentation

Architecture Overview

System Architecture

The Verse Proxy system is a modern microservices-based solution for Wialon IPS protocol testing and message processing:

Web Interface - Modern web-based testing interface with real-time monitoring
WebSocket Proxy - Real-time communication bridge (port 8080)
Connection Tracker - Real-time connection monitoring with WebSocket (port 8081)
TCP Socket Server - Wialon IPS protocol handling (port 3031)
Main Application - Core business logic and HTTP API (port 3030)
Kafka Infrastructure - Message broker with UI (ports 9092, 8082)
Redis - Connection state storage and caching (port 6379)

Data Flow

Message flow through the Kafka-based system:

Web Browser → WebSocket Proxy (port 8080)
WebSocket Proxy → TCP Socket Server (port 3031)
TCP Socket Server → Kafka Topics (port 9092)
Kafka → Connection Tracker Service
Connection Tracker → Redis (port 6379)
Connection Tracker → WebSocket Clients (port 8081)

Connection Tracker Service

Overview

The Connection Tracker Service provides real-time monitoring of TCP connections and device status. It integrates with Kafka for message processing and Redis for state storage.

Real-time Monitoring - Live connection tracking via WebSocket
Kafka Integration - Processes connection events from main app
Redis Storage - Stores connection state and device information
WebSocket API - Real-time updates to web clients

Features

Connection Events - Track new, update, and remove events
Device Information - Store IP, port, and device details
Real-time Updates - WebSocket notifications to clients
Health Monitoring - Built-in health checks and status reporting

WebSocket API

                    // Connect to Connection Tracker WebSocket

const ws = new WebSocket('ws://localhost:8081');

// Listen for connection events

ws.onmessage = (event) => {

  const data = JSON.parse(event.data);

  console.log('Connection event:', data);

};

// Event types: 'new', 'update', 'remove'

// Data includes: socketId, serverId, deviceInfo, timestamp

End-to-End Testing

Test Infrastructure

The project includes comprehensive E2E testing using Playwright:

Playwright Tests - Cross-browser testing framework
Mobile Testing - Responsive design validation
WebSocket Testing - Real-time connection validation
Docker Integration - Container-based testing

Test Scripts

run-all-e2e-tests.sh - Complete E2E test suite
run-comprehensive-tests.sh - Extended testing scenarios
test-system.sh - System health validation
veevvo-e2e-tests.spec.js - Main test specifications

Test Coverage

                    # Core Functionality Tests

- Web interface loading and navigation

- TCP connection testing

- WebSocket communication

- Connection tracking

- Mobile responsiveness

- Error handling

# Integration Tests

- Kafka message processing

- Redis state management

- Docker service communication

- Cross-service data flow

Port Configuration

Port	Service	Description	Access
80	Web Interface (Nginx)	Main web testing interface	http://localhost
8080	WebSocket Proxy	WebSocket to TCP bridge	ws://localhost:8080
8081	Connection Tracker WebSocket	Real-time connection monitoring	ws://localhost:8081
3030	Main Application (HTTP)	Health checks and API endpoints	http://localhost:3030
3031	TCP Socket Server	Wialon IPS protocol handling	localhost:3031
9092	Kafka	Message broker protocol	Internal only
8082	Kafka UI	Web-based topic management	http://localhost:8082
6379	Redis	Connection state storage	Internal only
2181	Zookeeper	Kafka coordination service	Internal only

Veevvo Protocol

Message Types

Login: #L#123456789012345;password
Data: #D#010120;120000;5544.6025;N;03739.6834;E;35;215;100;8;1.2;0;0;0;0;0
Short Data: #S#010120;120000;5544.6025;N;03739.6834;E;35;215;100;8;1.2;0;0;0;0;0
Black Box: #B#010120;120000;5544.6025;N;03739.6834;E;35;215;100;8;1.2;0;0;0;0;0
Custom: #C#010120;120000;5544.6025;N;03739.6834;E;35;215;100;8;1.2;0;0;0;0;0

Acknowledgments

All messages receive acknowledgments:

Login Ack: #AL#123456789012345
Data Ack: #AL#010120;120000;5544.6025;N;03739.6834;E;35;215;100;8;1.2;0;0;0;0;0

Development Commands

Local Development

                            
# Install dependencies

npm install

# Start all services with Docker

npm run docker:up

./scripts/docker-manager.sh start all

# Start main application

npm run start

# Development mode with auto-reload

npm run dev

# Start specific services

npm run start --workspace=@verse-proxy/connection-tracker

npm run start --workspace=@verse-proxy/main-app

Testing Commands

                            
# Run all tests

npm run test:all

# Run E2E tests

npm run test:e2e

./run-all-e2e-tests.sh

# Run comprehensive tests

./run-comprehensive-tests.sh

# Test system health

./test-system.sh

# Test TCP connection

./scripts/connection-checker.sh tcp localhost 3031

# Test HTTP endpoints

./scripts/connection-checker.sh http localhost 3030

Docker Management

Docker Manager Script

                            
# Start all services

./scripts/docker-manager.sh start all

# Start specific service

./scripts/docker-manager.sh start main-app

./scripts/docker-manager.sh start connection-tracker

# Stop all services

./scripts/docker-manager.sh stop all

# Check service status

./scripts/docker-manager.sh status

# View logs

./scripts/docker-manager.sh logs main-app

./scripts/docker-manager.sh logs connection-tracker

Manual Docker Commands

                            
# Start infrastructure (Kafka, Redis)

docker-compose -f config/docker/infrastructure/docker-compose.yml up -d

# Start main application

docker-compose -f services/main-app/docker-compose.yml up -d

# Start connection tracker

docker-compose -f services/connection-tracker/docker-compose.yml up -d

# Start web interface

docker-compose -f apps/web-interface/docker-compose.yml up -d

# Rebuild containers

docker-compose build --no-cache

Project Structure

                    
verse-proxy/

├── libs/                          # Shared libraries

│   ├── socket/                    # TCP socket library

│   ├── logger/                    # Logging utilities

│   ├── protocol/                  # Protocol handling (Kafka-based)

│   ├── utils/                     # Common utilities

│   └── redis/                     # Redis utilities

├── services/                      # Microservices

│   ├── main-app/                  # Main application service

│   │   ├── docker-compose.yml     # Main app Docker config

│   │   └── Dockerfile

│   ├── connection-tracker/        # Connection tracking service

│   │   ├── docker-compose.yml     # Connection tracker Docker config

│   │   └── Dockerfile

│   └── kafka-logger/             # Kafka logging service

├── apps/                          # Applications

│   └── web-interface/            # Web testing interface

│       ├── docker-compose.yml     # Web interface Docker config

│       ├── index.html             # Main web page

│       ├── script.js              # Frontend JavaScript

│       ├── docs.html              # This documentation page

│       └── connection-tracker-websocket.js # WebSocket service

├── config/                        # Configuration files

│   ├── docker/                    # Docker configurations

│   │   └── infrastructure/        # Shared infrastructure

│   └── env/                       # Environment configurations

├── scripts/                       # Build and deployment scripts

│   ├── docker-manager.sh          # Docker service management

│   ├── connection-checker.sh      # Connection testing utility

│   ├── deploy.sh                  # Deployment script

│   └── test/                      # Test scripts

├── tests/                         # Test files

│   ├── unit/                      # Unit tests

│   ├── integration/               # Integration tests

│   └── e2e/                       # End-to-end tests

├── run-all-e2e-tests.sh           # E2E test runner

├── run-comprehensive-tests.sh     # Comprehensive test runner

├── test-system.sh                 # System health tester

├── CLAUDE.md                      # AI assistant guidance

└── package.json                   # Root package.json (workspace)

Troubleshooting

Common Issues

Connection Refused: Check if services are running with ./scripts/docker-manager.sh status
Port Already in Use: Stop existing services first with ./scripts/docker-manager.sh stop all
WebSocket Connection Failed: Verify proxy is running on port 8080
Kafka Connection Errors: Ensure Kafka infrastructure is running
Redis Connection Issues: Check Redis service status

Connection Tracker Issues

WebSocket Connection Failed: Clear browser cache (Ctrl+F5) after code updates
No Connection Events: Check if Kafka is healthy and main app is publishing events
Service Not Responding: Verify Kafka and Redis are running
Wrong URL Detection: Frontend connects via nginx proxy at ws://localhost/connection-tracker

Health Checks

All Services: ./scripts/docker-manager.sh status
Main App: ./scripts/connection-checker.sh http localhost 3030
TCP Socket: ./scripts/connection-checker.sh tcp localhost 3031
Web Interface: curl http://localhost
Kafka UI: curl http://localhost:8082
Connection Tracker WS: curl -I http://localhost/connection-tracker (should return 426)
Redis: redis-cli ping

💡 Tip: Use ./scripts/connection-checker.sh for reliable TCP/HTTP testing without hanging!

Docker Troubleshooting

Outdated Container Code: Rebuild with docker-compose build --no-cache
Network Issues: Restart Docker with colima restart (macOS)
Service Dependencies: Start infrastructure first, then services
Log Analysis: Use ./scripts/docker-manager.sh logs [service]
Container Cleanup: docker system prune -a to clean up unused containers

Connection Checker Utility

Overview

The Connection Checker is a robust utility for testing TCP and HTTP connections without hanging. It's essential for both local development and remote deployment testing.

Key Features:

✅ No Hanging: Immediate results for both connection types
✅ Cross-Platform: Works on macOS and Linux
✅ Dual Support: TCP and HTTP connection testing
✅ Timeout Control: Configurable timeout for HTTP requests

Usage Examples

                            
# Test TCP connections (e.g., Wialon socket server)

./scripts/connection-checker.sh tcp localhost 3031

# Test HTTP connections (e.g., main app server)

./scripts/connection-checker.sh http localhost 3030

# Test with custom timeout (default is 5 seconds)

./scripts/connection-checker.sh http localhost 3030 10

# Test remote connections

./scripts/connection-checker.sh tcp test.veevvo.com 3031

./scripts/connection-checker.sh http test.veevvo.com 80

Common Test Scenarios

Local Development: Verify services are accessible
Remote Deployment: Test connectivity to production servers
Service Health: Quick health checks for TCP/HTTP endpoints
Network Debugging: Identify connection issues quickly

Technical Details

TCP Checks: Uses nc -z for reliable connection testing
HTTP Checks: Uses curl with timeout to /health endpoint
Exit Codes: 0 for success, 1 for failure
Dependencies: Requires nc (netcat) and curl

Обзор архитектуры

Системная архитектура

Система Verse Proxy - это современное микросервисное решение для тестирования протокола Wialon IPS и обработки сообщений:

Веб-интерфейс - Современный веб-интерфейс для тестирования с мониторингом в реальном времени
WebSocket прокси - Мост для связи в реальном времени (порт 8080)
Connection Tracker - Мониторинг соединений в реальном времени через WebSocket (порт 8081)
TCP Socket сервер - Обработка протокола Wialon IPS (порт 3031)
Основное приложение - Основная бизнес-логика и HTTP API (порт 3030)
Инфраструктура Kafka - Брокер сообщений с UI (порты 9092, 8082)
Redis - Хранение состояния соединений и кэширование (порт 6379)

Поток данных

Поток сообщений через систему на основе Kafka:

Веб-браузер → WebSocket прокси (порт 8080)
WebSocket прокси → TCP Socket сервер (порт 3031)
TCP Socket сервер → Kafka темы (порт 9092)
Kafka → Connection Tracker сервис
Connection Tracker → Redis (порт 6379)
Connection Tracker → WebSocket клиенты (порт 8081)

Микросервис Эмулятора Автомобилей

Обзор

Микросервис Эмулятора Автомобилей симулирует несколько автомобилей, отправляющих сообщения по протоколу Wialon IPS на TCP socket сервер. Каждый автомобиль поддерживает постоянный VIN и отправляет реалистичные данные телеметрии GPS.

Симуляция нескольких автомобилей - Настраиваемое количество автомобилей
Протокол Wialon IPS - Стандартный формат телеметрии GPS
Мониторинг в реальном времени - Веб-панель статуса
REST API - Программное управление и мониторинг

Возможности

Автоматическое переподключение - Грациозно обрабатывает сбои соединения
Несколько типов сообщений - Сообщения входа, данных, кратких данных и черного ящика
Реалистичные данные - Генерирует реалистичные GPS координаты и телеметрию
Мониторинг здоровья - Встроенные проверки здоровья и отчеты о статусе

Поддержка протокола Wialon IPS

                    #L#VIN;Password          // Сообщение входа
#D#DDMMYY;HHMMSS;DDMM.MMMM;N/S;DDDMM.MMMM;E/W;Speed;Course;Height;Satellites;HDOP;Inputs;Outputs;ADC;iButton;Params
#S#DDMMYY;HHMMSS;DDMM.MMMM;N/S;DDDMM.MMMM;E/W;Speed;Course;Height
#B#DDMMYY;HHMMSS;DDMM.MMMM;N/S;DDDMM.MMMM;E/W;Speed;Course;Height;Satellites;HDOP;Inputs;Outputs;ADC;iButton;Params
                

API Endpoints

Endpoint	Метод	Описание
`/api/status`	GET	Получить статус эмулятора и информацию об автомобилях
`/api/start`	POST	Запустить эмулятор автомобилей
`/api/stop`	POST	Остановить эмулятор автомобилей
`/api/restart`	POST	Перезапустить эмулятор автомобилей
`/api/send-message`	POST	Отправить пользовательское сообщение конкретному автомобилю
`/api/health`	GET	Endpoint проверки здоровья

Будущее развитие

Сервис хранения телеметрии

Планируемое развитие сервиса для хранения данных телеметрии по автомобилям, позволяющего:

Историческое отслеживание - Хранить и получать историю движения автомобилей
Визуализация карты - Отображать треки автомобилей и текущие местоположения
Аналитика - Анализировать поведение и паттерны автомобилей
Обновления в реальном времени - Живые обновления карты с текущими позициями автомобилей

Конфигурация портов

Порт	Сервис	Описание	Доступ
80	Веб-интерфейс (Nginx)	Основной веб-интерфейс для тестирования	http://localhost
8080	WebSocket прокси	Мост WebSocket к TCP	ws://localhost:8080
8081	Connection Tracker WebSocket	Мониторинг соединений в реальном времени	ws://localhost:8081
3030	Основное приложение (HTTP)	Проверки здоровья и API endpoints	http://localhost:3030
3031	TCP Socket сервер	Обработка протокола Wialon IPS	localhost:3031
9092	Kafka	Протокол брокера сообщений	Только внутренний
8082	Kafka UI	Веб-управление темами	http://localhost:8082
6379	Redis	Хранение состояния соединений	Только внутренний
2181	Zookeeper	Сервис координации Kafka	Только внутренний

Протокол Veevvo

Типы сообщений

Вход: #L#123456789012345;password
Данные: #D#010120;120000;5544.6025;N;03739.6834;E;35;215;100;8;1.2;0;0;0;0;0
Краткие данные: #S#010120;120000;5544.6025;N;03739.6834;E;35;215;100;8;1.2;0;0;0;0;0
Черный ящик: #B#010120;120000;5544.6025;N;03739.6834;E;35;215;100;8;1.2;0;0;0;0;0
Пользовательские: #C#010120;120000;5544.6025;N;03739.6834;E;35;215;100;8;1.2;0;0;0;0;0

Подтверждения

Все сообщения получают подтверждения:

Подтверждение входа: #AL#123456789012345
Подтверждение данных: #AL#010120;120000;5544.6025;N;03739.6834;E;35;215;100;8;1.2;0;0;0;0;0

Команды разработки

Локальная разработка

                            
# Установка зависимостей

npm install

# Запуск всех сервисов с Docker

npm run docker:up

./scripts/docker-manager.sh start all

# Запуск основного приложения

npm run start

# Режим разработки с автоперезагрузкой

npm run dev

# Запуск конкретных сервисов

npm run start --workspace=@verse-proxy/connection-tracker

npm run start --workspace=@verse-proxy/main-app

Команды тестирования

                            
# Запуск всех тестов

npm run test:all

# Запуск E2E тестов

npm run test:e2e

./run-all-e2e-tests.sh

# Запуск комплексных тестов

./run-comprehensive-tests.sh

# Тест системы

./test-system.sh

# Тест TCP соединения

./scripts/connection-checker.sh tcp localhost 3031

# Тест HTTP endpoints

./scripts/connection-checker.sh http localhost 3030

Управление Docker

Скрипт Docker Manager

                            
# Запуск всех сервисов

./scripts/docker-manager.sh start all

# Запуск конкретного сервиса

./scripts/docker-manager.sh start main-app

./scripts/docker-manager.sh start connection-tracker

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

./scripts/docker-manager.sh stop all

# Проверка статуса сервисов

./scripts/docker-manager.sh status

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

./scripts/docker-manager.sh logs main-app

./scripts/docker-manager.sh logs connection-tracker

Ручные команды Docker

                            
# Запуск инфраструктуры (Kafka, Redis)

docker-compose -f config/docker/infrastructure/docker-compose.yml up -d

# Запуск основного приложения

docker-compose -f services/main-app/docker-compose.yml up -d

# Запуск connection tracker

docker-compose -f services/connection-tracker/docker-compose.yml up -d

# Запуск веб-интерфейса

docker-compose -f apps/web-interface/docker-compose.yml up -d

# Пересборка контейнеров

docker-compose build --no-cache

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

                    
verse-proxy/

├── libs/                          # Общие библиотеки

│   ├── socket/                    # TCP socket библиотека

│   ├── logger/                    # Утилиты логирования

│   ├── protocol/                  # Обработка протоколов (на основе Kafka)

│   ├── utils/                     # Общие утилиты

│   └── redis/                     # Утилиты Redis

├── services/                      # Микросервисы

│   ├── main-app/                  # Основной сервис приложения

│   │   ├── docker-compose.yml     # Docker конфиг основного приложения

│   │   └── Dockerfile

│   ├── connection-tracker/        # Сервис отслеживания соединений

│   │   ├── docker-compose.yml     # Docker конфиг connection tracker

│   │   └── Dockerfile

│   └── kafka-logger/             # Сервис логирования Kafka

├── apps/                          # Приложения

│   └── web-interface/            # Веб-интерфейс для тестирования

│       ├── docker-compose.yml     # Docker конфиг веб-интерфейса

│       ├── index.html             # Главная веб-страница

│       ├── script.js              # Frontend JavaScript

│       ├── docs.html              # Эта страница документации

│       └── connection-tracker-websocket.js # WebSocket сервис

├── config/                        # Файлы конфигурации

│   ├── docker/                    # Docker конфигурации

│   │   └── infrastructure/        # Общая инфраструктура

│   └── env/                       # Конфигурации окружения

├── scripts/                       # Скрипты сборки и развертывания

│   ├── docker-manager.sh          # Управление Docker сервисами

│   ├── connection-checker.sh      # Утилита тестирования соединений

│   ├── deploy.sh                  # Скрипт развертывания

│   └── test/                      # Тестовые скрипты

├── tests/                         # Тестовые файлы

│   ├── unit/                      # Модульные тесты

│   ├── integration/               # Интеграционные тесты

│   └── e2e/                       # End-to-end тесты

├── run-all-e2e-tests.sh           # Запуск E2E тестов

├── run-comprehensive-tests.sh     # Запуск комплексных тестов

├── test-system.sh                 # Тестер здоровья системы

├── CLAUDE.md                      # Руководство для AI помощников

└── package.json                   # Корневой package.json (workspace)

Устранение неполадок

Частые проблемы

Соединение отклонено: Проверьте статус сервисов командой ./scripts/docker-manager.sh status
Порт уже используется: Остановите сервисы командой ./scripts/docker-manager.sh stop all
Ошибка WebSocket соединения: Убедитесь, что прокси работает на порту 8080
Ошибки подключения Kafka: Убедитесь, что инфраструктура Kafka запущена
Проблемы с Redis: Проверьте статус сервиса Redis

Проблемы Connection Tracker

Ошибка WebSocket соединения: Очистите кеш браузера (Ctrl+F5) после обновления кода
Нет событий соединения: Проверьте здоровье Kafka и что основное приложение публикует события
Сервис не отвечает: Убедитесь, что Kafka и Redis запущены
Неправильное определение URL: Frontend подключается через nginx прокси по адресу ws://localhost/connection-tracker

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

Все сервисы: ./scripts/docker-manager.sh status
Основное приложение: ./scripts/connection-checker.sh http localhost 3030
TCP Socket: ./scripts/connection-checker.sh tcp localhost 3031
Веб-интерфейс: curl http://localhost
Kafka UI: curl http://localhost:8082
Connection Tracker WS: curl -I http://localhost/connection-tracker (должен вернуть 426)
Redis: redis-cli ping

💡 Совет: Используйте ./scripts/connection-checker.sh для надежного тестирования TCP/HTTP без зависания!

Устранение неполадок Docker

Устаревший код в контейнере: Пересоберите с docker-compose build --no-cache
Проблемы с сетью: Перезапустите Docker командой colima restart (macOS)
Зависимости сервисов: Сначала запустите инфраструктуру, затем сервисы
Анализ логов: Используйте ./scripts/docker-manager.sh logs [service]
Очистка контейнеров: docker system prune -a для очистки неиспользуемых контейнеров

Утилита проверки соединений

Обзор

Connection Checker - это надежная утилита для тестирования TCP и HTTP соединений без зависания. Необходима как для локальной разработки, так и для тестирования удаленного развертывания.

Ключевые особенности:

✅ Без зависания: Мгновенные результаты для обоих типов соединений
✅ Кроссплатформенность: Работает на macOS и Linux
✅ Двойная поддержка: Тестирование TCP и HTTP соединений
✅ Контроль таймаута: Настраиваемый таймаут для HTTP запросов

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

                            
# Тест TCP соединений (например, Wialon socket сервер)

./scripts/connection-checker.sh tcp localhost 3031

# Тест HTTP соединений (например, основной сервер приложения)

./scripts/connection-checker.sh http localhost 3030

# Тест с пользовательским таймаутом (по умолчанию 5 секунд)

./scripts/connection-checker.sh http localhost 3030 10

# Тест удаленных соединений

./scripts/connection-checker.sh tcp test.veevvo.com 3031

./scripts/connection-checker.sh http test.veevvo.com 80

Частые сценарии тестирования

Локальная разработка: Проверка доступности сервисов
Удаленное развертывание: Тестирование подключения к продакшн серверам
Проверка здоровья сервисов: Быстрые проверки TCP/HTTP эндпоинтов
Отладка сети: Быстрое выявление проблем с соединениями

Технические детали

TCP проверки: Использует nc -z для надежного тестирования соединений
HTTP проверки: Использует curl с таймаутом к эндпоинту /health
Коды выхода: 0 для успеха, 1 для неудачи
Зависимости: Требует nc (netcat) и curl