refactor: reorganize project structure and add comprehensive documentation

- Organize components into subdirectories by type (layout, cards, sections, ui)
- Centralize TypeScript types in src/lib/types/
- Move documentation files to docs/ directory
- Create comprehensive PROJECT_STRUCTURE.md guide
- Add README files for lib/, utils/, tests/, and config/
- Set up test directory structure (unit, integration, e2e)
- Reorganize assets with icons subdirectory
- Fix favicon import path in layout
- Update component exports and imports to reflect new structure

This reorganization improves maintainability, discoverability, and follows
SvelteKit best practices for larger projects.

PROJECT_STRUCTURE.md

···
+# Jolly Whoppers - Project Structure
+
+This document provides a comprehensive overview of the project's directory structure and organization.
+
+## Project Root
+
+```
+jollywhoppers/
+├── .git/                   # Git repository data
+├── .svelte-kit/           # SvelteKit build artifacts (generated)
+├── .tangled/              # Tangled-specific files
+├── .vscode/               # VS Code workspace settings
+├── config/                # Additional configuration files
+├── docs/                  # Project documentation
+├── node_modules/          # Dependencies (generated)
+├── src/                   # Source code
+├── static/                # Static assets served at root
+├── tests/                 # Test files
+├── .gitignore            # Git ignore patterns
+├── .npmrc                # npm configuration
+├── .prettierignore       # Prettier ignore patterns
+├── .prettierrc           # Prettier configuration
+├── LICENSE               # Project license (AGPL-3.0)
+├── package.json          # Project dependencies and scripts
+├── pnpm-lock.yaml        # pnpm lock file
+├── pnpm-workspace.yaml   # pnpm workspace configuration
+├── PROJECT_STRUCTURE.md  # This file
+├── README.md             # Project README
+├── svelte.config.js      # SvelteKit configuration
+├── tsconfig.json         # TypeScript configuration
+└── vite.config.ts        # Vite build configuration
+```
+
+## Source Directory (`src/`)
+
+The main application source code.
+
+```
+src/
+├── lib/                  # Shared library code
+│   ├── assets/          # Static assets
+│   │   ├── brand/       # Brand assets (logos)
+│   │   ├── fonts/       # Custom fonts
+│   │   ├── icons/       # Icon files
+│   │   └── images/      # Image files
+│   ├── components/      # Svelte components
+│   │   ├── cards/       # Card components
+│   │   │   ├── MemberCard.svelte
+│   │   │   └── ProjectCard.svelte
+│   │   ├── layout/      # Layout components
+│   │   │   ├── Header.svelte
+│   │   │   └── Hero.svelte
+│   │   ├── sections/    # Section components
+│   │   │   ├── About.svelte
+│   │   │   ├── MemberGrid.svelte
+│   │   │   └── ProjectGrid.svelte
+│   │   ├── ui/          # UI components
+│   │   │   └── Avatar.svelte
+│   │   └── index.ts     # Component exports
+│   ├── services/        # Business logic services
+│   │   └── atproto/     # AT Protocol integration
+│   │       ├── agents.ts
+│   │       ├── cache.ts
+│   │       ├── index.ts
+│   │       ├── list.ts
+│   │       ├── README.md
+│   │       └── types.ts
+│   ├── styles/          # Global styles
+│   │   ├── open-props.css
+│   │   └── root-colours.css
+│   ├── types/           # TypeScript type definitions
+│   │   ├── components.ts
+│   │   └── index.ts
+│   ├── utils/           # Utility functions
+│   │   └── README.md
+│   ├── constants.ts     # Application constants
+│   ├── index.ts         # Main library exports
+│   └── README.md        # Library documentation
+├── routes/              # SvelteKit routes
+│   ├── +layout.svelte   # Root layout
+│   ├── +layout.ts       # Layout load function
+│   ├── +page.server.ts  # Server-side page logic
+│   └── +page.svelte     # Home page
+├── app.d.ts            # TypeScript app definitions
+└── app.html            # HTML template
+```
+
+## Tests Directory (`tests/`)
+
+All test files organized by test type.
+
+```
+tests/
+├── unit/               # Unit tests
+│   └── README.md
+├── integration/        # Integration tests
+│   └── README.md
+├── e2e/               # End-to-end tests
+│   └── README.md
+└── README.md          # Testing documentation
+```
+
+## Documentation Directory (`docs/`)
+
+Project documentation files.
+
+```
+docs/
+├── COMPONENTS.md       # Component documentation
+└── LUCIDE_ICONS.md    # Icon usage documentation
+```
+
+## Configuration Directory (`config/`)
+
+Additional configuration files (most configs remain at root for tool compatibility).
+
+```
+config/
+└── README.md          # Configuration documentation
+```
+
+## Static Directory (`static/`)
+
+Static files served at the root URL.
+
+```
+static/
+└── robots.txt         # Search engine crawler instructions
+```
+
+## Key Files
+
+### Root Configuration Files
+
+- **`package.json`** - Project metadata, dependencies, and npm scripts
+- **`tsconfig.json`** - TypeScript compiler configuration
+- **`svelte.config.js`** - SvelteKit framework configuration
+- **`vite.config.ts`** - Vite build tool configuration
+- **`.prettierrc`** - Code formatting rules
+- **`.gitignore`** - Files to exclude from Git
+
+### Application Entry Points
+
+- **`src/app.html`** - HTML template wrapper
+- **`src/routes/+layout.svelte`** - Root layout component
+- **`src/routes/+page.svelte`** - Home page component
+- **`src/lib/index.ts`** - Main library exports
+
+## Component Organization
+
+Components are organized by type:
+
+1. **Layout Components** (`components/layout/`)
+   - Page structure components (Header, Footer, Hero)
+   - Define overall page layout
+
+2. **Card Components** (`components/cards/`)
+   - Reusable card designs (ProjectCard, MemberCard)
+   - Display individual items in a consistent format
+
+3. **Section Components** (`components/sections/`)
+   - Major page sections (ProjectGrid, MemberGrid, About)
+   - Compose cards and content into cohesive sections
+
+4. **UI Components** (`components/ui/`)
+   - Generic, reusable UI elements (Avatar, Button, Input)
+   - Shared across multiple contexts
+
+## Type Organization
+
+Types are centralized in `src/lib/types/`:
+
+- **`components.ts`** - Component prop types
+- **`index.ts`** - Type re-exports for easy importing
+
+Import types using:
+```typescript
+import type { Project, Member, AboutItem } from '$lib/types';
+```
+
+## Service Organization
+
+Services contain business logic and API integrations:
+
+- **`atproto/`** - AT Protocol (Bluesky) integration
+  - List fetching
+  - Profile data
+  - Caching
+
+Add new services as subdirectories following the same pattern.
+
+## Asset Organization
+
+Assets are categorized by type:
+
+- **`brand/`** - Logo, wordmarks, brand guidelines
+- **`icons/`** - Icon files (favicon, app icons)
+- **`images/`** - Photos, illustrations, graphics
+- **`fonts/`** - Custom web fonts
+
+## Testing Organization
+
+Tests are organized by scope:
+
+- **`unit/`** - Test individual functions/components
+- **`integration/`** - Test multiple components working together
+- **`e2e/`** - Test complete user workflows
+
+## Import Path Aliases
+
+The project uses `$lib` as an alias for `src/lib`:
+
+```typescript
+// Instead of: import { Header } from '../../lib/components/Header.svelte'
+// Use: 
+import { Header } from '$lib/components';
+```
+
+## Build Artifacts
+
+Generated files (not committed to Git):
+
+- **`.svelte-kit/`** - SvelteKit build output
+- **`node_modules/`** - npm dependencies
+- **`build/`** - Production build output (if generated)
+
+## Best Practices
+
+1. **Follow the structure** - Place files in their designated locations
+2. **Use index files** - Simplify imports with barrel exports
+3. **Keep it organized** - Create subdirectories as needed
+4. **Document changes** - Update this file when structure changes
+5. **Use TypeScript** - Define types for everything
+6. **Test your code** - Write tests in the appropriate directory
+
+## Adding New Features
+
+### New Component
+1. Create in appropriate `components/` subdirectory
+2. Add to `components/index.ts`
+3. Add tests in `tests/unit/components/`
+
+### New Service
+1. Create in `services/` subdirectory
+2. Export from service index
+3. Add tests in `tests/unit/services/`
+
+### New Type
+1. Add to appropriate file in `types/`
+2. Export from `types/index.ts`
+
+### New Utility
+1. Create in `utils/` (organized by purpose)
+2. Add tests in `tests/unit/utils/`
+
+## Related Documentation
+
+- **`README.md`** - Project overview and getting started
+- **`src/lib/README.md`** - Library structure details
+- **`docs/COMPONENTS.md`** - Component usage guide
+- **`tests/README.md`** - Testing guidelines
+
+---
+
+**Last Updated:** December 2025
+**Version:** 2.0 (Reorganized Structure)

config/README.md

···
+# Configuration Directory
+
+This directory is reserved for additional configuration files that don't need to be at the project root.
+
+## Root Configuration Files
+
+The following configuration files remain at the project root for tool compatibility:
+- `.prettierrc` - Prettier formatting configuration
+- `.prettierignore` - Prettier ignore patterns
+- `.npmrc` - npm configuration
+- `tsconfig.json` - TypeScript configuration
+- `svelte.config.js` - SvelteKit configuration
+- `vite.config.ts` - Vite build tool configuration
+- `.gitignore` - Git ignore patterns
+
+## Future Use
+
+Add non-root configuration files here, such as:
+- Environment-specific configs
+- Custom build configurations
+- Tool-specific settings that support non-root locations

src/lib/README.md

···
+# Library Directory Structure
+
+This directory contains all shared code, components, and resources for the application.
+
+## Structure Overview
+
+```
+src/lib/
+├── assets/         # Static assets (images, icons, fonts, branding)
+├── components/     # Reusable Svelte components
+├── services/       # Business logic and API services
+├── styles/         # Global styles and design tokens
+├── types/          # TypeScript type definitions
+├── utils/          # Utility functions and helpers
+├── constants.ts    # Application constants and configuration
+└── index.ts        # Main library exports
+```
+
+## Directory Details
+
+### `assets/` - Static Assets
+Organized by asset type:
+- `assets/brand/` - Logo and brand assets
+- `assets/icons/` - Icon files (SVG, PNG)
+- `assets/images/` - Images and graphics
+- `assets/fonts/` - Custom font files
+
+### `components/` - Svelte Components
+Organized by component type:
+- `components/layout/` - Layout components (Header, Hero, Footer)
+- `components/cards/` - Card components (ProjectCard, MemberCard)
+- `components/sections/` - Section components (ProjectGrid, MemberGrid, About)
+- `components/ui/` - Reusable UI components (Avatar, Button, Input)
+
+Each component directory should include:
+- Component `.svelte` files
+- Component-specific types (if needed)
+- Component index for exports
+
+### `services/` - Business Logic
+Service modules organized by domain:
+- `services/atproto/` - AT Protocol integration
+- Add more services as needed (API clients, data fetching, etc.)
+
+### `styles/` - Global Styles
+- `styles/open-props.css` - Open Props imports
+- `styles/root-colours.css` - Brand color tokens
+- Additional global styles as needed
+
+### `types/` - TypeScript Types
+Centralized type definitions:
+- `types/components.ts` - Component prop types
+- `types/api.ts` - API response types (when needed)
+- `types/models.ts` - Data model types (when needed)
+
+### `utils/` - Utilities
+Helper functions organized by purpose:
+- String manipulation
+- Date formatting
+- Validation
+- API helpers
+
+## Import Patterns
+
+### Aliased Imports
+Use the `$lib` alias for all library imports:
+
+```typescript
+// Components
+import { Header, Hero, ProjectCard } from '$lib/components';
+
+// Types
+import type { Project, Member } from '$lib/types';
+
+// Services
+import { getListMembers } from '$lib/services/atproto';
+
+// Utils
+import { formatDate } from '$lib/utils/date';
+
+// Constants
+import { SITE_CONFIG, PROJECTS } from '$lib/constants';
+```
+
+### Direct Imports
+For more specific imports or tree-shaking:
+
+```typescript
+import Header from '$lib/components/layout/Header.svelte';
+import type { Project } from '$lib/types/components';
+```
+
+## Adding New Content
+
+### Adding a Component
+
+1. Create the component in the appropriate subdirectory
+2. Add to the component's index.ts
+3. Export from `components/index.ts` if widely used
+
+```typescript
+// src/lib/components/ui/Button.svelte
+<script lang="ts">
+  // Component code
+</script>
+
+// src/lib/components/index.ts
+export { default as Button } from './ui/Button.svelte';
+```
+
+### Adding a Type
+
+1. Add to appropriate file in `types/`
+2. Export from `types/index.ts`
+
+```typescript
+// src/lib/types/models.ts
+export type User = {
+  id: string;
+  name: string;
+};
+
+// src/lib/types/index.ts
+export type { User } from './models';
+```
+
+### Adding a Utility
+
+1. Create utility file in `utils/`
+2. Export functions
+3. Optionally add to `utils/index.ts`
+
+```typescript
+// src/lib/utils/string.ts
+export function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+```
+
+## Best Practices
+
+1. **Organize by feature/type** - Group related code together
+2. **Use index files** - Simplify imports with barrel exports
+3. **Keep components focused** - Single responsibility principle
+4. **Type everything** - Leverage TypeScript for safety
+5. **Document complex code** - Add comments for clarity
+6. **Test utilities** - Write unit tests for helpers
+7. **Reuse components** - Build composable, reusable pieces
+
+## File Naming Conventions
+
+- **Components**: PascalCase (e.g., `ProjectCard.svelte`)
+- **Types**: camelCase or PascalCase (e.g., `components.ts`)
+- **Utilities**: camelCase (e.g., `dateUtils.ts`)
+- **Constants**: SCREAMING_SNAKE_CASE in file (e.g., `SITE_CONFIG`)
+- **Files**: camelCase or kebab-case (e.g., `apiHelpers.ts` or `api-helpers.ts`)
+
+## Related Documentation
+
+- See `docs/COMPONENTS.md` for detailed component documentation
+- See `docs/LUCIDE_ICONS.md` for icon usage
+- See `tests/README.md` for testing guidelines

src/lib/components/MemberGrid.svelte src/lib/components/sections/MemberGrid.svelte

···
 <script lang="ts">
-	import MemberCard from './MemberCard.svelte';
+	import MemberCard from '../cards/MemberCard.svelte';
 
 	let {
 		title = 'Members',

src/lib/components/ProjectGrid.svelte src/lib/components/sections/ProjectGrid.svelte

···
 <script lang="ts">
-	import ProjectCard from './ProjectCard.svelte';
+	import ProjectCard from '../cards/ProjectCard.svelte';
 
 	let {
 		title = 'Projects',

src/lib/components/index.ts

···
 // Component exports for easy importing
-export { default as Header } from './Header.svelte';
-export { default as Hero } from './Hero.svelte';
-export { default as ProjectCard } from './ProjectCard.svelte';
-export { default as ProjectGrid } from './ProjectGrid.svelte';
-export { default as MemberCard } from './MemberCard.svelte';
-export { default as MemberGrid } from './MemberGrid.svelte';
-export { default as About } from './About.svelte';
-export { default as Avatar } from './Avatar.svelte';
 
-// Types
-export type Project = {
-	title: string;
-	href?: string;
-	// Optional project-specific fields
-	disabled?: boolean;
-	logo?: string;
-	handle?: string;
-};
+// Layout components
+export { default as Header } from './layout/Header.svelte';
+export { default as Hero } from './layout/Hero.svelte';
+
+// Card components
+export { default as ProjectCard } from './cards/ProjectCard.svelte';
+export { default as MemberCard } from './cards/MemberCard.svelte';
+
+// Section components
+export { default as ProjectGrid } from './sections/ProjectGrid.svelte';
+export { default as MemberGrid } from './sections/MemberGrid.svelte';
+export { default as About } from './sections/About.svelte';
 
-export type Member = {
-	title: string;
-	href: string;
-	avatar?: string;
-	handle: string;
-};
+// UI components
+export { default as Avatar } from './ui/Avatar.svelte';
 
-export type AboutItem = {
-	label: string;
-	href?: string;
-};
+// Re-export types for convenience
+export type { Project, Member, AboutItem } from '$lib/types';

src/lib/types/components.ts

···
+// Component type definitions
+export type Project = {
+	title: string;
+	href?: string;
+	// Optional project-specific fields
+	disabled?: boolean;
+	logo?: string;
+	handle?: string;
+};
+
+export type Member = {
+	title: string;
+	href: string;
+	avatar?: string;
+	handle: string;
+};
+
+export type AboutItem = {
+	label: string;
+	href?: string;
+};

src/lib/types/index.ts

···
+// Type exports for easy importing
+export type { Project, Member, AboutItem } from './components';

src/lib/utils/README.md

···
+# Utilities
+
+This directory contains utility functions and helper modules used throughout the application.
+
+## Structure
+
+Create subdirectories as needed:
+
+```
+utils/
+├── date/           # Date manipulation utilities
+├── string/         # String manipulation utilities
+├── validation/     # Validation helpers
+├── format/         # Formatting functions
+└── api/            # API helper functions
+```
+
+## Example Utilities
+
+### String Utilities (`utils/string.ts`)
+
+```typescript
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .trim()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/[\s_-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+export function truncate(text: string, length: number): string {
+  if (text.length <= length) return text;
+  return text.slice(0, length) + '...';
+}
+```
+
+### Date Utilities (`utils/date.ts`)
+
+```typescript
+export function formatDate(date: Date): string {
+  return new Intl.DateTimeFormat('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric'
+  }).format(date);
+}
+
+export function isValidDate(date: string): boolean {
+  return !isNaN(Date.parse(date));
+}
+```
+
+## Best Practices
+
+1. **Keep functions pure** - No side effects when possible
+2. **Single responsibility** - Each function does one thing well
+3. **Type everything** - Use TypeScript for type safety
+4. **Document complex logic** - Add JSDoc comments
+5. **Test utilities** - Write unit tests for all utilities
+6. **Export as needed** - Create index.ts for convenient imports
+
+## Usage
+
+```typescript
+// Import specific utilities
+import { slugify, truncate } from '$lib/utils/string';
+
+// Or import from index if available
+import { formatDate, slugify } from '$lib/utils';
+```

src/routes/+layout.svelte

···
 <script lang="ts">	
-	import favicon from '$lib/assets/favicon.svg';
+	import favicon from '$lib/assets/icons/favicon.svg';
 	import '$lib/styles/open-props.css';
 	import '$lib/styles/root-colours.css';
 

tests/README.md

···
+# Tests
+
+This directory contains all tests for the Jolly Whoppers project.
+
+## Structure
+
+```
+tests/
+├── unit/           # Unit tests for components, services, and utilities
+├── integration/    # Integration tests for multiple components/modules
+└── e2e/           # End-to-end tests for complete user workflows
+```
+
+## Test Types
+
+### Unit Tests (`tests/unit/`)
+- Test individual components in isolation
+- Test utility functions and services
+- Fast execution, no external dependencies
+- Mock all external dependencies
+
+### Integration Tests (`tests/integration/`)
+- Test multiple components working together
+- Test API integrations
+- Test page-level functionality
+- May use test databases or mock services
+
+### E2E Tests (`tests/e2e/`)
+- Test complete user workflows in a real browser
+- Test the application as end users would use it
+- Slowest but most comprehensive
+- Use actual application environment
+
+## Setup
+
+To set up testing, install a test framework:
+
+```bash
+# Vitest (recommended for unit/integration tests)
+pnpm add -D vitest @testing-library/svelte
+
+# Playwright (recommended for e2e tests)
+pnpm add -D @playwright/test
+```
+
+## Running Tests
+
+Add these scripts to `package.json`:
+
+```json
+{
+  "scripts": {
+    "test": "vitest",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:e2e": "playwright test",
+    "test:coverage": "vitest run --coverage"
+  }
+}
+```
+
+Then run:
+
+```bash
+# Run all tests
+pnpm test
+
+# Run specific test types
+pnpm test:unit
+pnpm test:integration
+pnpm test:e2e
+
+# Run with coverage
+pnpm test:coverage
+```
+
+## Best Practices
+
+1. **Write tests as you develop** - Don't wait until the end
+2. **Test behavior, not implementation** - Focus on what the code does, not how
+3. **Keep tests isolated** - Each test should be independent
+4. **Use descriptive names** - Test names should explain what they test
+5. **Maintain tests** - Update tests when features change
+6. **Aim for good coverage** - But don't obsess over 100%
+
+## Resources
+
+- [Vitest Documentation](https://vitest.dev/)
+- [Testing Library](https://testing-library.com/)
+- [Playwright Documentation](https://playwright.dev/)
+- [SvelteKit Testing Guide](https://kit.svelte.dev/docs/testing)

tests/e2e/README.md

···
+# End-to-End Tests
+
+Place end-to-end tests here for testing complete user workflows in a browser environment.
+
+## Structure
+
+```
+e2e/
+├── user-flows/     # Complete user journey tests
+├── pages/          # Page-specific e2e tests
+└── fixtures/       # Test data and fixtures
+```
+
+## Tools
+
+Consider using:
+- [Playwright](https://playwright.dev/) - Modern e2e testing framework
+- [Cypress](https://www.cypress.io/) - Popular e2e testing framework
+
+## Example (Playwright)
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('home page loads correctly', async ({ page }) => {
+  await page.goto('/');
+  await expect(page.locator('h1')).toContainText('Jolly Whoppers');
+  await expect(page.locator('.project-grid')).toBeVisible();
+});
+```
+
+## Running Tests
+
+```bash
+pnpm test:e2e
+```

tests/integration/README.md

···
+# Integration Tests
+
+Place integration tests here for testing multiple components, modules, or services working together.
+
+## Structure
+
+```
+integration/
+├── api/            # API integration tests
+├── pages/          # Page-level integration tests
+└── flows/          # User flow integration tests
+```
+
+## Example
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/svelte';
+import HomePage from '$lib/routes/+page.svelte';
+
+describe('Home Page Integration', () => {
+  it('displays all sections correctly', () => {
+    const { getByText } = render(HomePage);
+    expect(getByText('Projects')).toBeTruthy();
+    expect(getByText('About')).toBeTruthy();
+  });
+});
+```
+
+## Running Tests
+
+```bash
+pnpm test:integration
+```

tests/unit/README.md

···
+# Unit Tests
+
+Place unit tests here for individual components, functions, and modules.
+
+## Structure
+
+```
+unit/
+├── components/     # Component unit tests
+├── services/       # Service unit tests
+└── utils/          # Utility function tests
+```
+
+## Example
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/svelte';
+import Header from '$lib/components/layout/Header.svelte';
+
+describe('Header', () => {
+  it('renders correctly', () => {
+    const { container } = render(Header);
+    expect(container).toBeTruthy();
+  });
+});
+```
+
+## Running Tests
+
+```bash
+pnpm test:unit
+```