WebWizard/docs/architecture.md

WebWizard - MVP Architektúra

Tento dokument definuje technickú architektúru pre prvú verziu (MVP) projektu WebWizard. Cieľom je maximálna jednoduchosť, rýchlosť vývoja a nulová závislosť na komplexných infraštruktúrach (databáza, cloud služby).

---

1. Celková architektúra systému

Systém funguje na princípe Single-Page Application (SPA) komunikujúcej s tenkým Backendom cez AJAX.

[ Používateľ (Prehliadač) ]
      |
      | AJAX (POST /ajax.php)
      v
[ PHP Backend (ajax.php) ] <----> [ Súborový systém (JSON & HTML) ]
      |
      | Lokálne API Call (HTTP)
      v
[ AI Engine (DAIAPI) ]

Princípy:

• Stateless Backend: PHP neudržiava session v pamäti, identita používateľa sa posiela v každej požiadavke.
• File-based Persistence: Všetky dáta sú v JSON súboroch.
• Local AI Integration: Systém využíva lokálnu inštanciu DAIAPI, čo znižuje latenciu a náklady.
• Decoupled Frontend: Frontend je čisté HTML/JS, ktoré možno hostovať kdekoľvek.

---

2. Použité technológie

• Backend: PHP 8.2+ (bez frameworku).
• Frontend: Vanilla JavaScript (ES6+), HTML5, Vanilla CSS.
• AI: DAIAPI (lokálne HTTP rozhranie pre LLM).
• Server: Apache/Nginx s podporou .htaccess (na ochranu dátových priečinkov).
• Balíčkovací manažér: Composer (voliteľne pre pomocné knižnice).

---

3. Adresárová štruktúra

/
├── data/               # NEPRÍSTUPNÉ Z WEBU (.htaccess deny all)
│   ├── users/          # <user_id>.json
│   └── projects/       # <project_id>.json
├── sites/              # PRÍSTUPNÉ Z WEBU (Vygenerované weby)
│   └── a8f7c3d1/       # Konkrétny vygenerovaný web
│       ├── index.html
│       ├── assets/
│       ├── images/
│       └── config.json # Kópia konfigurácie pre daný export
├── src/                # PHP Logika
│   ├── Actions/        # Triedy pre jednotlivé AJAX akcie
│   ├── Services/       # AI Engine (DAIAPI Wrapper), FileStorage, Renderer
│   └── Utils/          # Helpery
├── public/             # Root webservera
│   ├── index.html      # Hlavná aplikácia (Wizard)
│   ├── ajax.php        # Jediný vstupný bod pre API
│   ├── css/
│   └── js/
├── vendor/             # Composer závislosti
└── composer.json

---

4. Štruktúra dát (JSON)

Používateľ (data/users/<user_id>.json)

{
  "user_id": "u_9b12ef44",
  "created_at": "2026-06-11T10:00:00Z",
  "projects": ["p_a8f7c3d1", "p_b2c3d4e5"]
}

Projekt (data/projects/<project_id>.json)

{
  "project_id": "p_a8f7c3d1",
  "user_id": "u_9b12ef44",
  "status": "in_progress",
  "current_step": 3,
  "wizard_data": {
    "business_type": "restaurant",
    "name": "Pizza Marco",
    "city": "Košice"
  },
  "generated_at": null,
  "site_path": "/sites/a8f7c3d1/"
}

---

5. Identifikácia používateľa

Riešenie: LocalStorage + HTTP Header.

1. Pri prvej návšteve JS skontroluje localStorage.getItem('ww_user_id').
2. Ak neexistuje, pošle požiadavku na action=initSession.
3. Backend vygeneruje unikátny hash (napr. bin2hex(random_bytes(8))) a vráti ho.
4. JS ho uloží do localStorage.
5. V každej ďalšej AJAX požiadavke sa tento ID posiela v HTTP hlavičke X-User-ID.

Zdôvodnenie:

• Čistejšie API: Payload obsahuje len dáta súvisiace s akciou, identita je v metadátach (hlavičkách).
• Jednoduchšia autorizácia na úrovni backendu ešte pred parsovaním JSON tela.
• LocalStorage je pre SPA prirodzenejší a nevyžaduje riešenie CSRF tokenov v takej miere ako automaticky posielané cookies.

---

6. AJAX Komunikácia

Všetky požiadavky smerujú na public/ajax.php.

Formát požiadavky:

POST /ajax.php Content-Type: application/json X-User-ID: u_9b12ef44

{
  "action": "saveStep",
  "project_id": "p_a8f7c3d1",
  "payload": {
    "step": 2,
    "data": { "name": "Pizza Marco" }
  }
}

Zoznam akcií:

• initSession: Vytvorí nového používateľa.
• listProjects: Vráti zoznam projektov používateľa.
• createProject: Inicializuje nový projekt.
• saveStep: Uloží rozpracované dáta z wizardu.
• generateWebsite: Spustí AI generovanie a vytvorí súbory.
• getProjectStatus: Pre polling počas generovania.

---

7. Generovanie a publikovanie

Workflow:

1. Spracovanie dát: PHP vezme wizard_data z JSON súboru.
2. AI Prompt: Service vytvorí systémový prompt a pošle ho do DAIAPI cez HTTP POST.
3. Parsing: DAIAPI vráti vygenerovaný obsah (text/JSON).
4. Templating:
   • PHP prečíta základnú HTML šablónu (v /src/Templates/).
   • Nahradí placeholdery (napr. {{BUSINESS_NAME}}) vygenerovaným obsahom.
5. Súborový systém:
   • Vytvorí priečinok /sites/<project_id>/.
   • Nakopíruje statické assety (CSS, JS).
   • Zapíše index.html.
6. Relatívne URL: Všetky cesty v šablóne sú /assets/style.css -> v kóde menené na assets/style.css (relatívne k index.html).

---

8. Bezpečnosť (MVP)

1. Ochrana dát: .htaccess v priečinku /data/ s obsahom Deny from all.
2. Sanitizácia: PHP htmlspecialchars() pri renderovaní vygenerovaného obsahu (prevencia XSS).
3. Path Traversal: Validácia user_id a project_id (iba alfanumerické znaky), aby sa predišlo prístupu k súborom mimo určených priečinkov.
4. Rate Limiting: Jednoduchá kontrola počtu požiadaviek na IP adresu v ajax.php.

---

9. Budúce rozširovanie

• Databáza: Trieda FileStorageService sa nahradí DatabaseStorageService implementujúcou rovnaké rozhranie.
• Vlastné domény: Webserver sa nakonfiguruje tak, aby doména smerovala do konkrétneho /sites/<id>/ priečinka. Relatívne URL toto umožňujú bez zmeny kódu.
• Editor: Pridá sa nová AJAX akcia updateContent, ktorá prepíše konkrétne časti v index.html alebo v config.json a znova vyrenderuje stránku.
• Auth: Pridá sa tabuľka (alebo JSON) credentials, ktorá prepojí user_id s emailom a heslom.