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

# 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!

# 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/	reset_password	GET, POST
/verify-email/	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/	company_detail
/company/	company_detail_by_slug
/company//recommend	company_recommend
/osoba/	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/	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/	settings_blocks_remove	POST
/dashboard	dashboard	GET

3.2 Blueprint: forum

Route	Endpoint
/forum	forum_index
/forum/nowy	forum_new_topic
/forum/	forum_topic
/forum//odpowiedz	forum_reply
/admin/forum	admin_forum
/admin/forum/topic//pin	admin_forum_pin
/admin/forum/topic//lock	admin_forum_lock
/admin/forum/topic//delete	admin_forum_delete_topic
/admin/forum/reply//delete	admin_forum_delete_reply
/admin/forum/topic//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/	messages_view
/wiadomosci//odpowiedz	messages_reply
/api/messages/unread-count	api_messages_unread

4.2 Blueprint: notifications (API)

Route	Endpoint
/api/notifications	api_notifications_list
/api/notifications//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//message	api_chat_message
/api/chat//history	api_chat_history
/api/chat/conversations	api_chat_conversations
/api/chat//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

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

# 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

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

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

2. Testowanie po każdej fazie

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

# Testy manualne każdego route

3. Procedura wdrożenia

# 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@57.128.200.27 "cd /var/www/nordabiznes && sudo -u www-data git pull && sudo systemctl restart nordabiznes"

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

4. Rollback

git revert HEAD
git push origin master && git push inpi master
ssh maciejpi@57.128.200.27 "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)