# Codebase Summary: Vibery Kits Website

## Directory Structure

```
website/
├── src/
│   ├── components/          (19 files)
│   │   ├── astro/          Deprecated, merged into root
│   │   └── vue/            (7 Vue interactive components)
│   ├── composables/         (5 TypeScript composables)
│   ├── data/               (4 JSON data files + backups)
│   ├── layouts/            (1 master layout)
│   ├── pages/              (12 route pages)
│   ├── styles/             (1 global stylesheet)
│   └── types/              (2 TypeScript interfaces)
├── scripts/                (2 CLI tools)
├── public/                 (favicon, robots.txt)
├── .claude/                (Skills, config)
└── dist/                   (Build output)
```

## File Inventory

### Components (19 Total)

**Astro Components (12 Static):**
| File | Lines | Purpose |
|------|-------|---------|
| Header.astro | 48 | Navigation, logo, cart button |
| Hero.astro | 188 | Hero section, search, outcome wizard |
| Footer.astro | 34 | Footer links, copyright |
| TemplateCard.astro | 94 | Individual template card |
| TemplatesGrid.astro | 37 | Grid container (has neon-\* refs) |
| StacksGrid.astro | 118 | Smart stacks grid display |
| FilterBar.astro | 62 | Category filters + sort dropdown |
| Modal.astro | 98 | Static modal structure (deprecated) |
| Cart.astro | 83 | Cart sidebar markup (deprecated) |
| ClientScripts.astro | 451 | Legacy client JS (has neon refs) |
| ClaudeKitBrowser.astro | 102 | Stats/metrics display |
| ClaudeKitCTA.astro | 66 | CTA copy + pricing |

**Vue Components (7 Interactive):**
| File | Lines | Purpose |
|------|-------|---------|
| SearchBar.vue | 264 | Live search with MiniSearch, dropdown, keyboard nav |
| FilterBar.vue | 47 | Filter pills, state |
| CartSidebar.vue | 162 | Cart with useCart hook |
| TemplateModal.vue | 217 | Full Vue modal (dynamic content) |
| AppWrapper.vue | 75 | Root app orchestrator |
| NotificationToast.vue | 40 | Toast notification system |
| TemplateInteractions.vue | 249 | Event handler bridge |

### Data Files (4 JSON)

| File           | Lines | Size  | Purpose                |
| -------------- | ----- | ----- | ---------------------- |
| templates.json | 1,413 | ~48KB | 600+ template catalog  |
| stacks.json    | 208   | ~8KB  | 12 curated stacks      |
| outcomes.json  | 434   | ~15KB | 8 outcome wizard flows |
| claudekit.json | 162   | ~5KB  | Premium product data   |

### Composables (5 TypeScript)

| File                | Lines | Purpose                               |
| ------------------- | ----- | ------------------------------------- |
| useCart.ts          | 109   | Cart state, localStorage, command gen |
| useModal.ts         | 34    | Modal open/close, current item        |
| useSearch.ts        | 146   | MiniSearch indexing + fuzzy matching  |
| useNotifications.ts | 47    | Toast notification queue              |
| useUsageStats.ts    | 75    | Analytics tracking                    |

**useSearch.ts Details:**

- MiniSearch engine for fast full-text search
- Unified index across templates + stacks
- Fuzzy matching (0.2 tolerance, 0.3 for short queries)
- Field boosting: name (3x), tags (2x), category/type (1.5x), description (1x)
- Returns up to 8 results, sorted by relevance
- Singleton pattern with lazy initialization

### Pages (12 Routes)

| Route                     | Template                | Purpose                    |
| ------------------------- | ----------------------- | -------------------------- |
| /                         | index.astro             | Home, featured content     |
| /agents                   | agents.astro            | Type filter: agents        |
| /commands                 | commands.astro          | Type filter: commands      |
| /mcps                     | mcps.astro              | Type filter: MCPs          |
| /hooks                    | hooks.astro             | Type filter: hooks         |
| /settings                 | settings.astro          | Type filter: settings      |
| /stacks                   | stacks.astro            | Stacks listing grid        |
| /stacks/[id]              | stacks/[id].astro       | Dynamic stack detail (SSG) |
| /claudekit                | claudekit.astro         | Premium product page       |
| /guides                   | guides/index.astro      | Guides hub                 |
| /guides/what-is-claudekit | what-is-claudekit.astro | Educational                |
| /guides/free-vs-premium   | free-vs-premium.astro   | Educational                |

### Types (2 TypeScript Interfaces)

| File        | Purpose                           |
| ----------- | --------------------------------- |
| template.ts | Template interface (6-type union) |
| cart.ts     | CartItem interface                |

### Layouts

| File         | Purpose                              |
| ------------ | ------------------------------------ |
| Layout.astro | Master layout (SEO, ViewTransitions) |

## Build Pipeline

**Build Tool:** Astro v5.0.0
**Adapter:** @astrojs/cloudflare (static output)
**Styling:** Tailwind CSS v3.4.1 + @astrojs/tailwind
**Theming:** Warm Terminal color system (CSS classes)
**Icons:** Phosphor Icons v2.1.2
**Deployment:** Cloudflare Pages

## Tech Stack

```json
{
  "framework": "Astro 5.0.0",
  "view_library": "Vue 3.4.0",
  "styling": "Tailwind CSS 3.4.1",
  "css_framework": "@astrojs/tailwind 6.0.2",
  "icons": "@phosphor-icons/web 2.1.2",
  "cloudflare_adapter": "@astrojs/cloudflare 12.0.0",
  "sitemap": "@astrojs/sitemap 3.6.0",
  "vue_integration": "@astrojs/vue 5.0.0"
}
```

## Naming Conventions

- **Files:** kebab-case (Header.astro, SearchBar.vue)
- **Components:** PascalCase (Header, SearchBar, CartSidebar)
- **Classes:** Tailwind + warm-\* prefix (warm-bg-deep, warm-text-primary)
- **Composables:** useXxx pattern (useCart, useModal)
- **Routes:** kebab-case directories

## Design System: Warm Terminal

### Color Tokens (Tailwind Config)

| Token               | Hex     | Purpose           |
| ------------------- | ------- | ----------------- |
| warm-bg-deep        | #0c0a09 | Main background   |
| warm-bg-surface     | #1c1917 | Card backgrounds  |
| warm-bg-elevated    | #292524 | Hover state       |
| warm-bg-hover       | #44403c | Active state      |
| warm-text-primary   | #fafaf9 | Primary text      |
| warm-text-secondary | #a8a29e | Secondary text    |
| warm-text-tertiary  | #78716c | Tertiary text     |
| warm-text-muted     | #57534e | Muted text        |
| warm-accent         | #e07256 | Terracotta accent |
| warm-accent-hover   | #c85a42 | Accent hover      |

### Typography

- **Sans:** Satoshi (headings, UI)
- **Mono:** IBM Plex Mono (code snippets)

## Known Issues

1. **Legacy Client JS:** ClientScripts.astro (451 lines) duplicates Vue logic
   - Contains neon-\* class references (outdated)
   - Should be migrated to Vue composables

2. **Dual Implementations:**
   - Cart exists in Cart.astro (legacy) + CartSidebar.vue (active)
   - Modal exists in Modal.astro (legacy) + TemplateModal.vue (active)
   - FilterBar exists in FilterBar.astro (legacy) + FilterBar.vue (active)

3. **Neon Class References:**
   - TemplatesGrid.astro (minor refs)
   - ClientScripts.astro (in JS strings)

## State Management

**Pattern:** Vue 3 Composition API with composables
**Persistence:** localStorage (cart)
**Scope:** Shared across Vue islands via AppWrapper.vue

### State Stores

| Store         | Ref                | Persisted      |
| ------------- | ------------------ | -------------- |
| Cart          | useCart()          | ✓ localStorage |
| Modal         | useModal()         | ✗              |
| Notifications | useNotifications() | ✗              |
| Search        | useSearch()        | ✗              |
| Analytics     | useUsageStats()    | ✓ localStorage |

## Testing

**Framework:** Vitest v4.0.16
**Coverage Tool:** v8 coverage
**DOM:** happy-dom (lightweight)
**Vue Testing:** @vue/test-utils v2.4.6

**Test Files:**

- `src/__tests__/useSearch.test.ts` - 54 test cases, MiniSearch/fuzzy/edge cases
- `src/__tests__/SearchBar.test.ts` - Component integration tests
- `src/__tests__/performance.test.ts` - Performance benchmarks

**Coverage:** 96.87%

**Commands:**

```bash
npm test                    # Watch mode
npm run test:run           # Single run
npm run test:coverage      # Coverage report
npm run test:ui            # Vitest UI dashboard
```

## CLI Commands

```bash
# Template operations
npm run tpl:report          # Health check
npm run tpl:validate        # Cross-reference
npm run tpl:backup          # Export JSON
npm run tpl:regen           # Regenerate registry

# Data operations
npm run data:validate       # Validate JSON schemas

# Development
npm run dev                 # Dev server (http://localhost:4321)
npm run build              # Production build
npm run preview            # Local production preview

# Testing
npm test                   # Run tests (watch)
npm run test:run          # Run tests (single)
npm run test:coverage     # Coverage report
npm run test:ui           # UI dashboard
```

## Build Metrics

**Repomix Stats:**

- Total Files: 71
- Total Tokens: 172,527
- Largest Files: outcomes.json (4,342 tokens), templates.json (top by size)

## Deployment Configuration

**Platform:** Cloudflare Pages
**Build Command:** `astro build`
**Build Output:** `dist/`
**Site URL:** https://vibery.app/products/vibery-kits

## Integration Points

- **Parent Repo:** `/Applications/MAMP/htdocs/vibe-templates/`
- **CLI Tool:** `/Applications/MAMP/htdocs/vibe-templates/cli/`
- **Templates:** `/Applications/MAMP/htdocs/claude-code-templates/` (600+ templates)