init
This commit is contained in:
326
ARCHITECTURE.md
Normal file
326
ARCHITECTURE.md
Normal file
@@ -0,0 +1,326 @@
|
||||
# Архитектура 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
|
||||
Reference in New Issue
Block a user