# 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)