Web Activity Tracker

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

Fullstack приложение для отслеживания событий (event tracking) с архитектурой на базе:

• Frontend: React + TypeScript + Vite
• Backend: Node.js + Express + TypeScript
• Database: MongoDB (Mongoose)
• Web Server: Nginx (production)

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

Архитектура

┌─────────────┐
│   Client    │ (React приложение)
│  Port 5173  │
└──────┬──────┘
       │
       │ HTTP запросы
       ▼
┌─────────────┐     ┌─────────────┐
│    Nginx    │────▶│   Server    │
│  Port 80    │     │  Port 3000  │
└─────────────┘     └──────┬──────┘
                           │
                           │ MongoDB queries
                           ▼
                    ┌─────────────┐
                    │   MongoDB   │
                    │  Port 27017 │
                    └─────────────┘

Компоненты

• Frontend (apps/client): React SPA с системой трекинга событий
• Backend (apps/server): Express API с валидацией и сохранением событий
• Database: MongoDB с коллекцией tracks для хранения событий
• Nginx: Reverse proxy и статический файловый сервер в production

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

Запуск через Docker Compose (Production)

1. Создайте файлы с переменными окружения:

cp .env.example .env

2. Запустите все сервисы:

docker-compose up --build

3. Проверьте работу:

• Frontend: http://localhost:8080
• API Health: http://localhost:8080/health
• Tracker Script: http://localhost:8080/tracker

Запуск вручную (Development)

Для разработки можно запускать компоненты отдельно:

1. MongoDB

1. Запусти MongoDB (можно через docker compose up -d build)
2. Убедись, что переменная для подключения в .env - корректна.

2. Backend Server

# Установите зависимости
npm install

# Запустите в режиме разработки (с hot-reload)
npm run dev

# Или соберите и запустите production версию
npm run build
npm start

# Запустите миграции (если нужно)
npm run migrate

Сервер будет доступен на http://localhost:3000

3. Frontend Client

cd apps/client

# Создайте .env.client файл в корне проекта
cp ../../.env.example .env

# Установите зависимости
npm install

# Запустите dev сервер
npm run dev

# Или соберите для production
npm run build
npm run preview

Frontend будет доступен на http://localhost:5173

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

Backend (.env)

Переменная	Описание	Значение по умолчанию
SERVER_PORT	Порт сервера	3000
MONGODB_URI	URI подключения к MongoDB	mongodb://localhost:27017/tracker
MONGODB_TIMEOUT	Таймаут подключения (мс)	5000
MONGODB_SOCKET_TIMEOUT	Таймаут сокета (мс)	45000
NODE_ENV	Окружение	development
TRACKER_API_URL	URL трекера для клиента	http://localhost:3000/track
CLIENT_ORIGIN	Разрешенные origins для CORS	http://localhost:5173

Frontend (.env)

Переменная	Описание	Значение по умолчанию
VITE_TRACKER_SCRIPT_URL	URL для трекера	http://localhost:3000/tracker

API Endpoints

GET /health

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

Response:

{
  "status": "ok"
}

GET /tracker

Возвращает JavaScript скрипт трекера с подставленным URL API.

Response: JavaScript файл

POST /track

Сохраняет события трекера в базу данных.

Request Body:

[
  {
    "id": "uuid-here",
    "event": "pageview",
    "tags": ["tag1", "tag2"],
    "url": "https://example.com/page",
    "title": "Page Title",
    "ts": 1234567890
  }
]

Response:

• 200 - События приняты (сохранение происходит асинхронно)
• 400 - Невалидный JSON
• 422 - Невалидный формат событий

Валидация событий:

• Массив должен быть непустым
• Каждое событие должно содержать:
  • id (string, непустой)
  • event (string, непустой)
  • tags (array of strings)
  • url (string)
  • title (string, опционально)
  • ts (number, положительный integer - Unix timestamp в секундах)

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

.
├── apps/
│   ├── client/              # React фронтенд
│   │   ├── src/
│   │   │   ├── analytics/  # Логика трекера
│   │   │   └── ...
│   │   └── package.json
│   └── server/              # Express бэкенд
│       ├── src/
│       │   ├── configs/     # Конфигурации (CORS, Helmet)
│       │   ├── database/    # Работа с БД
│       │   │   ├── schema/  # Mongoose схемы
│       │   │   ├── services/# Сервисы БД
│       │   │   ├── migrations/ # Миграции
│       │   │   └── validation/ # Валидация
│       │   ├── tracker/     # Скрипт трекера для клиента
│       │   └── index.ts     # Точка входа
│       └── package.json
├── nginx/               # Nginx конфигурация
│       ├── Dockerfile       # Multi-stage build (client + nginx)
│       └── nginx.conf       # Конфигурация прокси
├── docker-compose.yml       # Оркестрация всех сервисов
└── README.md

База данных

Коллекция tracks

Схема документа:

{
  _id: ObjectId,           // MongoDB ID
  id: string,              // UUID события (с клиента)
  event: string,           // Тип события
  tags: string[],          // Массив тегов
  url: string,             // URL страницы
  title: string,           // Заголовок страницы
  ts: number,              // Unix timestamp (секунды)
  createdAt: Date,         // Дата создания записи
  updatedAt: Date          // Дата обновления
}

Индексы

• id - для поиска по ID события
• event - для фильтрации по типу события
• ts - для сортировки по времени
• createdAt - для временных запросов
• Составной: { event: 1, ts: -1 } - для частых запросов

Проверка данных в MongoDB

Для проверки сохраненных событий:

# Подключиться к MongoDB и посмотреть все события
docker-compose exec mongo mongosh tracker --eval "db.tracks.find().pretty()"

# Посчитать количество событий
docker-compose exec mongo mongosh tracker --eval "db.tracks.countDocuments()"

# Статистика по типам событий
docker-compose exec mongo mongosh tracker --eval "db.tracks.aggregate([{ \$group: { _id: '\$event', count: { \$sum: 1 } } }, { \$sort: { count: -1 } }])"

# Последние 5 событий
docker-compose exec mongo mongosh tracker --eval "db.tracks.find().sort({ createdAt: -1 }).limit(5).pretty()"