# Архитектура 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

```sql
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

```sql
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()
);
```

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

### Логирование

```javascript
// 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

```bash
npm install
npm run dev
```

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

### Production

```bash
# 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