# 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`.