# Annotated Source Code — Every Line Explained

This folder contains **annotated copies** of **every** file in `src/`. Each line of the original code is followed or preceded by a comment explaining:

- **What** the syntax means (TypeScript, React, Next.js)
- **Why** it exists in the Kött Gård project

Production code in `src/` stays clean. Learning comments live here only.

## Regenerate all annotations

```bash
node docs/annotate-all.mjs
```

Run this after you change source files to refresh the annotated copies.

## Folder mirror

```
docs/annotated/src/          ← you are here (annotated)
src/                         ← real app code (no line comments)
```

| Annotated path | Original path |
|----------------|---------------|
| `docs/annotated/src/app/page.annotated.tsx` | `src/app/page.tsx` |
| `docs/annotated/src/lib/products.annotated.ts` | `src/lib/products.ts` |
| `docs/annotated/src/store/cart.annotated.ts` | `src/store/cart.ts` |
| … | (52 files total) |

## File categories

| Folder | What it contains |
|--------|------------------|
| `app/` | Pages and routes (Next.js App Router) |
| `components/` | Reusable UI (home sections, layout, product cards) |
| `lib/` | Data, images, constants, helpers |
| `store/` | Zustand global state (cart, auth, wishlist, locale) |
| `i18n/` | Translations (Swedish, English, Urdu) |
| `hooks/` | Custom React hooks |
| `types/` | TypeScript interfaces |

## How to read

1. Open the **original** file in `src/` in your editor.
2. Open the matching **`.annotated.ts`** or **`.annotated.tsx`** file side-by-side.
3. Read the gray `//` comment above each line, then the code.

## Programming languages in this project

| Language | Role |
|----------|------|
| **TypeScript** | Types catch errors before run; interfaces for Product, Cart, Order |
| **React 18** | Components + JSX UI; hooks for state and effects |
| **Next.js 13** | File-based routing, layouts, metadata, image optimization |
| **Tailwind CSS** | Utility classes for burgundy/cream/gold design |
| **Zustand** | Global stores with `persist` → localStorage |

## Related documents

- Word guide: `docs/Kottgard-Website-Guide.docx`
- Visual guide: `../kottgard documentation/16-website-visual-and-code-guide.md`