nordabiz/docs/MODULAR_MONOLITH_PLAN.md

# Plan Refaktoryzacji: Modularny Monolit

> **Data utworzenia:** 2026-01-31
> **Status:** ✅ UKOŃCZONE (2026-02-09)
> **Cel:** Redukcja app.py z 15,570 → ~500 linii
> **Wynik:** app.py zredukowane do 1,557 linii (-90%). 17 blueprintów, 49 plików z routami.

---

## Stan obecny

### Metryki app.py

| Metryka | Wartość |
|---------|---------|
| Linie kodu | 15,570 |
| Routes (@app.route) | 235 |
| Funkcje (def) | 258 |
| Funkcje pomocnicze | ~30 |

### Rozkład routes według kategorii

| Kategoria | Ilość routes | Linie (szac.) | Priorytet |
|-----------|--------------|---------------|-----------|
| admin/* | 85 | ~4,000 | Średni |
| api/* | 85 | ~3,500 | Średni |
| zopk/* | 32 | ~2,500 | Niski |
| public (/, /company, /search) | ~20 | ~800 | Wysoki |
| forum/* | ~15 | ~600 | Średni |
| auth (login, register) | 8 | ~500 | Wysoki |
| account (konto, settings) | 13 | ~500 | Średni |
| messages (wiadomości) | ~10 | ~400 | Średni |
| chat/* | 8 | ~400 | Niski |
| audits (seo, gbp, it, krs) | ~25 | ~2,000 | Niski |
| honeypot | 10 | ~20 | Niski |

### Blueprinty - aktualny stan

| Blueprint | Status | Linie | Routes |
|-----------|--------|-------|--------|
| reports | ✅ Wdrożony | 198 | 4 |
| community/contacts | ✅ Wdrożony | ~200 | 6 |
| community/classifieds | ✅ Wdrożony | ~250 | 4 |
| community/calendar | ✅ Wdrożony | ~200 | 3 |
| education | ✅ Wdrożony | 59 | 2 |
| **Razem wdrożone** | | **~900** | **19** |
| **Pozostało w app.py** | | **~14,700** | **216** |

### Funkcje pomocnicze do wydzielenia

```python
# utils/validators.py
validate_email(email)
validate_password(password)
sanitize_input(text, max_length)

# utils/notifications.py
create_notification(user_id, title, message, ...)
create_news_notification(company_id, news_id, news_title)

# utils/analytics.py
get_or_create_analytics_session()
track_conversion(event_type, company_id, ...)
track_page_view()
log_brave_api_call(user_id, feature, company_name)

# utils/security.py
check_geoip()
set_security_headers(response)
is_admin_exempt()

# utils/api_usage.py
get_free_tier_usage()
get_brave_api_usage()

# utils/filters.py
ensure_url_filter(url)
```

---

## Analiza zależności

### Funkcje pomocnicze

| Funkcja | Lokalizacja | Status |
|---------|-------------|--------|
| `sanitize_input()` | utils/helpers.py | ✅ Gotowe |
| `validate_email()` | utils/helpers.py | ✅ Gotowe |
| `validate_password()` | utils/helpers.py | ✅ Gotowe |
| `ensure_url()` | utils/helpers.py | ✅ Gotowe |
| `admin_required` | utils/decorators.py | ✅ Gotowe |
| `verified_required` | utils/decorators.py | ✅ Gotowe |

### Dekoratory - zależności krytyczne!

```python
# utils/decorators.py używa:
url_for('auth.login')      # Wymaga blueprintu 'auth'
url_for('public.index')    # Wymaga blueprintu 'public'
```

**WNIOSEK:** Blueprinty `auth` i `public` muszą być wdrożone RAZEM, zanim można używać dekoratorów w innych blueprintach.

### Graf zależności

```
utils/helpers.py ──────────────────────────────────────┐
       │                                                │
       ▼                                                │
utils/decorators.py ─────► wymaga: auth + public        │
       │                                                │
       ▼                                                │
┌──────────────────────────────────────────────────────┴─┐
│  FAZA 2 (KRYTYCZNA - razem!)                           │
│  ┌─────────┐    ┌─────────┐                            │
│  │  auth   │◄──►│  public │  ◄── wzajemne url_for     │
│  └─────────┘    └─────────┘                            │
└────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────┐
│  FAZA 3+: Wszystkie pozostałe blueprinty                │
│  - mogą używać utils/decorators.py                      │
│  - mogą używać url_for('auth.login')                    │
│  - mogą używać url_for('public.index')                  │
└─────────────────────────────────────────────────────────┘
```

---

## Plan fazowy (z uwzględnieniem zależności)

### Faza 2: Auth + Public (RAZEM - KRYTYCZNA!)

**Szacowany czas:** 4-5 godzin
**Redukcja app.py:** ~1,300 linii
**WAŻNE:** Te dwa blueprinty MUSZĄ być wdrożone razem!

#### 2.1 Blueprint: auth

| Route | Endpoint | Metody |
|-------|----------|--------|
| /register | register | GET, POST |
| /login | login | GET, POST |
| /logout | logout | GET |
| /verify-2fa | verify_2fa | GET, POST |
| /forgot-password | forgot_password | GET, POST |
| /reset-password/<token> | reset_password | GET, POST |
| /verify-email/<token> | verify_email | GET |
| /resend-verification | resend_verification | GET, POST |

**Zależności:**
- `validate_email()`, `validate_password()`
- `send_registration_notification()`
- Flask-Login

#### 2.2 Blueprint: public

| Route | Endpoint |
|-------|----------|
| / | index |
| /company/<id> | company_detail |
| /company/<slug> | company_detail_by_slug |
| /company/<slug>/recommend | company_recommend |
| /osoba/<id> | person_detail |
| /search | search |
| /aktualnosci | events |
| /nowi-czlonkowie | new_members |
| /mapa-polaczen | connections_map |
| /release-notes | release_notes |

**Po wdrożeniu Fazy 2:**
- `url_for('auth.login')` działa ✅
- `url_for('public.index')` działa ✅
- Można używać `utils/decorators.py` w kolejnych fazach ✅

---

### Faza 3: Account + Forum

**Szacowany czas:** 3-4 godziny
**Redukcja app.py:** ~1,100 linii
**Zależności:** auth, public (Faza 2)

#### 3.1 Blueprint: account

| Route | Endpoint | Metody |
|-------|----------|--------|
| /konto | account_index | GET, POST |
| /konto/prywatnosc | account_privacy | GET, POST |
| /konto/bezpieczenstwo | account_security | GET |
| /konto/blokady | account_blocks | GET |
| /konto/blokady/dodaj | account_blocks_add | POST |
| /konto/blokady/usun/<id> | account_blocks_remove | POST |
| /settings/2fa | settings_2fa | GET, POST |
| /settings/privacy | settings_privacy | GET, POST |
| /settings/blocks | settings_blocks | GET |
| /settings/blocks/add | settings_blocks_add | POST |
| /settings/blocks/remove/<id> | settings_blocks_remove | POST |
| /dashboard | dashboard | GET |

#### 3.2 Blueprint: forum

| Route | Endpoint |
|-------|----------|
| /forum | forum_index |
| /forum/nowy | forum_new_topic |
| /forum/<id> | forum_topic |
| /forum/<id>/odpowiedz | forum_reply |
| /admin/forum | admin_forum |
| /admin/forum/topic/<id>/pin | admin_forum_pin |
| /admin/forum/topic/<id>/lock | admin_forum_lock |
| /admin/forum/topic/<id>/delete | admin_forum_delete_topic |
| /admin/forum/reply/<id>/delete | admin_forum_delete_reply |
| /admin/forum/topic/<id>/status | admin_forum_change_status |

---

### Faza 4: Messages + Notifications

**Szacowany czas:** 2 godziny
**Redukcja app.py:** ~600 linii

#### 4.1 Blueprint: messages

| Route | Endpoint |
|-------|----------|
| /wiadomosci | messages_inbox |
| /wiadomosci/wyslane | messages_sent |
| /wiadomosci/nowa | messages_new |
| /wiadomosci/wyslij | messages_send |
| /wiadomosci/<id> | messages_view |
| /wiadomosci/<id>/odpowiedz | messages_reply |
| /api/messages/unread-count | api_messages_unread |

#### 4.2 Blueprint: notifications (API)

| Route | Endpoint |
|-------|----------|
| /api/notifications | api_notifications_list |
| /api/notifications/<id>/read | api_notifications_read |
| /api/notifications/read-all | api_notifications_read_all |
| /api/notifications/unread-count | api_notifications_unread |

---

### Faza 5: Chat (NordaGPT)

**Szacowany czas:** 2 godziny
**Redukcja app.py:** ~400 linii

| Route | Endpoint |
|-------|----------|
| /chat | chat_index |
| /api/chat/settings | api_chat_settings |
| /api/chat/start | api_chat_start |
| /api/chat/<id>/message | api_chat_message |
| /api/chat/<id>/history | api_chat_history |
| /api/chat/conversations | api_chat_conversations |
| /api/chat/<id>/delete | api_chat_delete |
| /api/chat/feedback | api_chat_feedback |

---

### Faza 6: Admin panels

**Szacowany czas:** 6-8 godzin
**Redukcja app.py:** ~4,000 linii

#### 6.1 admin/users (~10 routes)
#### 6.2 admin/fees (~5 routes)
#### 6.3 admin/analytics (~10 routes)
#### 6.4 admin/ai (~5 routes)
#### 6.5 admin/status (~10 routes)
#### 6.6 admin/security (~5 routes)
#### 6.7 admin/announcements (~10 routes)
#### 6.8 admin/recommendations (~5 routes)

---

### Faza 7: Audits

**Szacowany czas:** 4-5 godzin
**Redukcja app.py:** ~2,000 linii

#### 7.1 audits/seo (~10 routes)
#### 7.2 audits/gbp (~5 routes)
#### 7.3 audits/social (~5 routes)
#### 7.4 audits/it (~10 routes)
#### 7.5 audits/krs (~5 routes)
#### 7.6 audits/digital (~2 routes)

---

### Faza 8: ZOPK

**Szacowany czas:** 4-5 godzin
**Redukcja app.py:** ~2,500 linii

| Moduł | Routes |
|-------|--------|
| zopk/public | 4 |
| zopk/admin | 5 |
| zopk/news | 15 |
| zopk/knowledge | 20 |
| zopk/timeline | 8 |

---

### Faza 9: API misc + Honeypot

**Szacowany czas:** 2 godziny
**Redukcja app.py:** ~500 linii

- api/validation (check-email, verify-nip, verify-krs)
- api/analytics (track, heartbeat, scroll, error, performance)
- api/recommendations
- api/companies
- api/connections
- honeypot (wp-admin, .env, etc.)

---

### Faza 10: Utils extraction

**Szacowany czas:** 2 godziny

Wydzielenie funkcji pomocniczych:
- utils/validators.py
- utils/notifications.py
- utils/analytics.py
- utils/security.py
- utils/api_usage.py
- utils/filters.py

---

## Docelowa struktura

```
nordabiz/
├── app.py                    # ~500 linii (tylko init + config)
├── config.py                 # Konfiguracja środowisk
├── extensions.py             # Flask extensions (csrf, limiter, login)
│
├── blueprints/
│   ├── __init__.py           # register_blueprints()
│   │
│   ├── auth/                 # Faza 2
│   │   ├── __init__.py
│   │   └── routes.py
│   │
│   ├── account/              # Faza 2
│   │   ├── __init__.py
│   │   └── routes.py
│   │
│   ├── public/               # Faza 3
│   │   ├── __init__.py
│   │   └── routes.py
│   │
│   ├── forum/                # Faza 3
│   │   ├── __init__.py
│   │   └── routes.py
│   │
│   ├── messages/             # Faza 4
│   │   ├── __init__.py
│   │   └── routes.py
│   │
│   ├── chat/                 # Faza 5
│   │   ├── __init__.py
│   │   └── routes.py
│   │
│   ├── admin/                # Faza 6
│   │   ├── __init__.py
│   │   ├── users.py
│   │   ├── fees.py
│   │   ├── analytics.py
│   │   ├── ai.py
│   │   ├── status.py
│   │   ├── security.py
│   │   ├── announcements.py
│   │   └── recommendations.py
│   │
│   ├── audits/               # Faza 7
│   │   ├── __init__.py
│   │   ├── seo.py
│   │   ├── gbp.py
│   │   ├── social.py
│   │   ├── it.py
│   │   ├── krs.py
│   │   └── digital.py
│   │
│   ├── zopk/                 # Faza 8
│   │   ├── __init__.py
│   │   ├── public.py
│   │   ├── admin.py
│   │   ├── news.py
│   │   ├── knowledge.py
│   │   └── timeline.py
│   │
│   ├── api/                  # Faza 9
│   │   ├── __init__.py
│   │   ├── validation.py
│   │   ├── analytics.py
│   │   ├── recommendations.py
│   │   ├── companies.py
│   │   └── connections.py
│   │
│   ├── community/            # ✅ Faza 1 (DONE)
│   │   ├── contacts/
│   │   ├── classifieds/
│   │   └── calendar/
│   │
│   ├── reports/              # ✅ Faza 1 (DONE)
│   │
│   └── education/            # ✅ Faza 1 (DONE)
│
├── utils/                    # Faza 10
│   ├── __init__.py
│   ├── validators.py
│   ├── notifications.py
│   ├── analytics.py
│   ├── security.py
│   ├── api_usage.py
│   ├── filters.py
│   ├── decorators.py         # ✅ Istnieje
│   └── helpers.py            # ✅ Istnieje
│
└── services/                 # ✅ Istnieje (14 plików)
    ├── gemini_service.py
    ├── search_service.py
    ├── email_service.py
    └── ...
```

---

## Harmonogram szacunkowy

| Faza | Zakres | Czas | Zależności | Status |
|------|--------|------|------------|--------|
| 1 | reports, community, education | 4h | utils/helpers | ✅ DONE |
| **2** | **auth + public (RAZEM!)** | **5h** | **utils/helpers** | ✅ DONE |
| 3 | account, forum | 4h | Faza 2 | ✅ DONE |
| 4 | messages, notifications | 2h | Faza 2 | ✅ DONE |
| 5 | chat | 2h | Faza 2 | ✅ DONE |
| 6 | admin (8 modułów) | 8h | Faza 2 + decorators | ✅ DONE |
| 7 | audits (6 modułów) | 5h | Faza 2 + decorators | ✅ DONE |
| 8 | zopk (5 modułów) | 5h | Faza 2 + decorators | ✅ DONE |
| 9 | api misc, honeypot | 2h | Faza 2 | ✅ DONE |
| 10 | cleanup (usunięcie duplikatów z app.py) | 2h | Wszystkie fazy | ✅ DONE |
| **RAZEM** | | **~39h** | | |

**⚠️ UWAGA:** Faza 2 jest krytyczna - `auth` i `public` muszą być wdrożone RAZEM!

**Szczegółowa strategia:** [`docs/MODULAR_MONOLITH_DEPLOYMENT_STRATEGY.md`](MODULAR_MONOLITH_DEPLOYMENT_STRATEGY.md)

### Strategia "Alias Bridge" (bezpieczna)

| Podfaza | Opis | Ryzyko |
|---------|------|--------|
| **2a** | Blueprinty + aliasy dla starych nazw | 🟢 Niskie |
| **2b** | Stopniowa migracja szablonów | 🟢 Niskie |
| **2c** | Usunięcie aliasów | 🟢 Niskie |

**Kluczowa technika:** Rejestracja tego samego URL pod dwoma nazwami
```python
# Po rejestracji blueprintu:
app.add_url_rule('/login', 'login', app.view_functions['auth.login'])

# Efekt:
url_for('login')      → /login  ✓ (stary kod działa)
url_for('auth.login') → /login  ✓ (nowy kod działa)
```

---

## Zasady refaktoryzacji

### 1. url_for w blueprintach

```python
# Wewnątrz blueprintu - z kropką
url_for('.endpoint')

# W szablonach - pełna nazwa
url_for('blueprint.endpoint')
```

### 2. Testowanie po każdej fazie

```bash
# Lokalnie
python3 app.py
curl http://localhost:5000/health

# Testy manualne każdego route
```

### 3. Procedura wdrożenia

```bash
# 1. Commit lokalny
git add . && git commit -m "refactor(phase-X): ..."

# 2. Test lokalny

# 3. Push
git push origin master && git push inpi master

# 4. Deploy
ssh maciejpi@10.22.68.249 "cd /var/www/nordabiznes && sudo -u www-data git pull && sudo systemctl restart nordabiznes"

# 5. Weryfikacja produkcji
curl https://nordabiznes.pl/health
```

### 4. Rollback

```bash
git revert HEAD
git push origin master && git push inpi master
ssh maciejpi@10.22.68.249 "cd /var/www/nordabiznes && sudo -u www-data git pull && sudo systemctl restart nordabiznes"
```

---

## Metryki sukcesu

| Metryka | Przed | Po | Cel |
|---------|-------|-----|-----|
| Linie app.py | 15,570 | ~500 | -97% |
| Routes w app.py | 235 | ~5 | -98% |
| Funkcje w app.py | 258 | ~10 | -96% |
| Blueprinty | 5 | ~25 | +400% |
| Czas uruchomienia | ? | bez zmian | = |
| Funkcjonalność | 100% | 100% | = |

---

**Ostatnia aktualizacja:** 2026-02-09 (status: UKOŃCZONE)