pg-adminus/ARCHITECTURE.md

Архитектура PG-Admin

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

Трёхслойная архитектура

┌─────────────────────────────────────────────┐
│           Presentation Layer                 │
│    (Frontend - React-like модули)            │
│  - module-based structure                    │
│  - CSS isolation per module                  │
│  - Theme switching                           │
└──────────────┬──────────────────────────────┘
               │
┌──────────────┴──────────────────────────────┐
│          Application Layer                   │
│  (JavaScript - SPA Router, API Client)       │
│  - Client-side routing                       │
│  - State management                          │
│  - API communication                         │
└──────────────┬──────────────────────────────┘
               │
┌──────────────┴──────────────────────────────┐
│           API Layer (Backend)                │
│    (Express.js - RESTful API)                │
│  - Authentication routes                     │
│  - User management routes                    │
│  - Database routes                           │
│  - Admin routes                              │
└──────────────┬──────────────────────────────┘
               │
┌──────────────┴──────────────────────────────┐
│          Data Access Layer                   │
│     (PostgreSQL Database)                    │
│  - users table                               │
│  - activity_logs table                       │
│  - user-managed tables                       │
└─────────────────────────────────────────────┘

Frontend архитектура

Модульная структура

public/
├── index.html                    # Main SPA container
├── modules/
│   ├── auth/
│   │   └── login.html           # Auth module template
│   ├── dashboard/
│   │   └── dashboard.html       # Dashboard module template
│   └── admin/
│       └── admin-panel.html     # Admin module template
├── styles/
│   ├── main.css                 # Global styles (components)
│   ├── theme.css                # Dark/Light mode
│   ├── responsive.css           # Mobile-first responsive
│   └── animations.css           # Transitions & animations
└── js/
    ├── theme.js                 # Theme management
    ├── api.js                   # API client
    ├── auth.js                  # Auth logic
    ├── router.js                # SPA routing
    └── app.js                   # App orchestration

Разделение ответственности

theme.js

• Управление темой (dark/light)
• Сохранение в localStorage
• Синхронизация с системными настройками

api.js

• Централизованный API клиент
• Обработка ошибок
• Таймауты и retries

auth.js

• Логика аутентификации
• Проверка прав доступа
• Управление сессией

router.js

• SPA навигация (hash-based)
• Проверка авторизации для маршрутов
• Динамическая загрузка модулей

app.js

• Координация компонентов
• Локальное состояние приложения
• Обработка глобальных событий

Модули

Каждый модуль состоит из:

module/
├── module.html          # HTML/UI
├── styles/
│   └── module.css      # Module-specific styles (если нужно)
└── js/
    └── module.js       # Module-specific logic (если нужно)

Backend архитектура

Структура маршрутов

src/routes/
├── auth.js              # POST /api/auth/login
│                        # POST /api/auth/register
│                        # GET /api/auth/me
│                        # POST /api/auth/logout
│
├── users.js             # GET /api/users
│                        # POST /api/users
│                        # PATCH /api/users/:id
│                        # DELETE /api/users/:id
│
├── db-tables.js         # GET /api/db/tables
│                        # GET /api/db/tables/:tableName/data
│                        # POST /api/db/query
│                        # GET /api/db/stats
│
└── admin.js             # GET /api/admin/stats
                         # GET /api/admin/logs
                         # GET /api/admin/backups
                         # POST /api/admin/backups

Middleware

┌────────────────────────────┐
│   Request Middleware       │
├────────────────────────────┤
│ 1. Parse JSON (express)    │
│ 2. CORS                    │
│ 3. Session                 │
│ 4. Auth verification       │
│ 5. Role verification       │
└────────┬───────────────────┘
         │
    Route Handler
         │
┌────────┴───────────────────┐
│  Response Middleware       │
├────────────────────────────┤
│ 1. Error handling          │
│ 2. JSON serialization      │
└────────────────────────────┘

Поток аутентификации

1. User enters credentials
         │
         ▼
2. POST /api/auth/login
         │
         ▼
3. Hash verification (bcryptjs)
         │
    ├─ SUCCESS ───▶ Create session
    │               Set session.userId
    │               Return user data
    │
    └─ FAIL ───▶ Return error
         │
         ▼
4. Store session in cookie
         │
         ▼
5. Client stores auth state

Защита данных

Password Security

• Хеширование bcryptjs (10 rounds)
• Никогда не передаем пароль на фронтенд
• Secure cookies (httpOnly, secure flag в production)

API Security

• Session-based authentication
• Проверка прав доступа на каждый запрос
• SQL injection protection (parameterized queries)
• CORS с серверной стороны

Модель данных

Users Table

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    password VARCHAR(255) NOT NULL,
    role VARCHAR(50) NOT NULL DEFAULT 'viewer',
    active BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

Activity Logs Table

CREATE TABLE activity_logs (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
    action VARCHAR(255),
    details JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

Диагностика и мониторинг

Логирование

// Activity logging
await pool.query(
    'INSERT INTO activity_logs (user_id, action, details) VALUES ($1, $2, $3)',
    [userId, 'action_name', JSON.stringify({...details})]
);

Обработка ошибок

Все ошибки логируются:

• Console.error для разработки
• Activity logs для действий пользователей
• Graceful error responses для клиента

Масштабирование

Готовность к масштабированию

Горизонтальное масштабирование:

• Session store можно перенести в Redis
• API stateless для load balancing
• Docker контейнеризация

Вертикальное масштабирование:

• Database connection pooling (pg library)
• Кеширование запросов
• Индексирование таблиц

Развертывание

Development

npm install
npm run dev

Приложение на localhost:3000 с hot reload

Production

# Build Docker image
docker build -t pg-admin .

# Run with Docker Compose
docker-compose up -d

# Or manual run
NODE_ENV=production npm start

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

NODE_ENV=production
PORT=3000
SESSION_SECRET=strong-random-secret
DB_HOST=prod-db.example.com
DB_PORT=5432
DB_NAME=app_db
DB_USER=app_user
DB_PASSWORD=app_password

Нефункциональные требования

Производительность

• Первая загрузка: < 2s
• Навигация: < 500ms (SPA)
• Запросы к БД: < 1s
• API响応: < 100ms (от БД)

Масштабируемость

• Одновременные пользователи: 100+
• Записи в БД: 1,000,000+
• Размер БД: 10GB+

Доступность

• Uptime: 99.5%
• MTBF: > 720 часов
• MTTR: < 1 часа

Security Considerations

1. Input Validation - Все входные данные проверяются
2. Output Encoding - XSS protection через параметризованные шаблоны
3. Authentication - Session-based с хешированием
4. Authorization - Role-based access control (RBAC)
5. Encryption - HTTPS в production
6. Logging - Все действия записываются

---

Дата обновления: Январь 2024
Версия: 2.0.0
Автор: PG-Admin Team