From 563ef9ea253a94da022fa551cb112df18b6c3b2c Mon Sep 17 00:00:00 2001 From: igor Date: Thu, 11 Jun 2026 16:49:49 +0200 Subject: [PATCH] added architecture specification for project --- docs/architecture.md | 177 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 docs/architecture.md diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..6336abc --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,177 @@ +# 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. + +```ascii +[ 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 + +```text +/ +├── data/ # NEPRÍSTUPNÉ Z WEBU (.htaccess deny all) +│ ├── users/ # .json +│ └── projects/ # .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/.json`) +```json +{ + "user_id": "u_9b12ef44", + "created_at": "2026-06-11T10:00:00Z", + "projects": ["p_a8f7c3d1", "p_b2c3d4e5"] +} +``` + +### Projekt (`data/projects/.json`) +```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` + +```json +{ + "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//`. + * 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//` 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.