klimat24/docs/specs/01-architecture.md

01 — Architektura

Definiuje strukturę projektu, routing i wzorce. Trzymaj się jej ściśle.

---

Struktura katalogów

.
├── AGENTS.md
├── app/
│   ├── layout.tsx              # root layout: font, header, footer, metadata bazowe
│   ├── page.tsx                # strona główna
│   ├── globals.css             # Tailwind + CSS variables (tokeny)
│   ├── klimatyzacja/
│   │   └── page.tsx
│   ├── pompy-ciepla/
│   │   └── page.tsx
│   ├── uslugi-domowe/
│   │   ├── page.tsx            # rozdzielnik
│   │   ├── remonty/page.tsx
│   │   ├── hydraulika/page.tsx
│   │   └── serwis-agd/page.tsx
│   ├── realizacje/
│   │   └── page.tsx
│   ├── blog/
│   │   ├── page.tsx
│   │   └── [slug]/page.tsx
│   ├── o-nas/page.tsx
│   ├── kontakt/
│   │   ├── page.tsx
│   │   └── actions.ts          # Server Action formularza
│   ├── sklep/
│   │   ├── page.tsx            # listing + filtry
│   │   └── [slug]/page.tsx     # karta produktu
│   ├── koszyk/page.tsx
│   ├── raty/page.tsx
│   ├── (formalne)/             # route group dla stron formalnych
│   │   ├── regulamin/page.tsx
│   │   ├── polityka-prywatnosci/page.tsx
│   │   ├── reklamacje/page.tsx
│   │   ├── dostawa/page.tsx
│   │   └── gwarancja/page.tsx
│   ├── sitemap.ts
│   ├── robots.ts
│   ├── not-found.tsx
│   └── loading.tsx
├── components/
│   ├── ui/                     # shadcn/ui (button, card, accordion, input, ...)
│   ├── layout/                 # Header, Footer, MobileMenu, TrustBar, NavDropdown
│   ├── sections/               # sekcje stron: Hero, ServicesGrid, ProcessSteps, FAQ, ...
│   ├── shop/                   # ProductCard, ProductFilters, CartSummary, ...
│   └── common/                 # SectionHeading, CTAButton, StatCounter, Placeholder, ...
├── content/                    # dane (mock): products.ts, projects.ts, posts.ts, faq.ts, ...
├── lib/                        # utils.ts, constants.ts, cart-store.ts (zustand), validations.ts (zod)
├── types/                      # product.ts, project.ts, post.ts, ...
├── public/                     # zdjęcia placeholder, logo, ikony, og-images
├── tailwind.config.ts
└── tsconfig.json               # alias @/*

---

Zasady routingu

• App Router, Server Components domyślnie.
• Strony formalne w route group (formalne) — wspólny, prosty layout tekstowy.
• Dynamiczne trasy: blog/[slug], sklep/[slug] — generateStaticParams z danych w content/.
• Każda strona eksportuje metadata (lub generateMetadata dla dynamicznych).

---

Wzorce komponentów

1. Strona = kompozycja sekcji. page.tsx importuje komponenty z components/sections/ i przekazuje im dane. Strona nie zawiera logiki layoutu sekcji.
2. Sekcja = jeden komponent. Np. HeroSection, ServicesGrid, ProcessSteps, FaqAccordion, PricingTable, Testimonials, StatsBar, BlogPreview, CtaBanner.
3. Współdzielone bloki (Hero, FAQ, CTA) przyjmują propsy, by można było ich użyć na wielu stronach z różną treścią — nie duplikuj.
4. Dane oddzielone od prezentacji — komponent dostaje dane przez propsy, źródło to content/.
5. Client Components tylko: formularze, koszyk (Zustand), dropdowny nawigacji, mobile menu, slidery galerii, kalkulator rat, filtry sklepu.

---

Stan aplikacji

• Koszyk: Zustand store w lib/cart-store.ts (dodaj/usuń/zmień ilość/suma). Persist do localStorage.
• Reszta: stan lokalny komponentów. Bez globalnego store poza koszykiem.

---

Obsługa obrazów

• Wszystkie zdjęcia jako placeholdery na tym etapie (komponent Placeholder lub pliki w public/).
• W kodzie oznacz komentarzem {/* TODO: docelowe zdjęcie — opis */}, gdzie wstawić realne foto.
• Zawsze next/image z alt, width/height lub fill + sizes.