# CRUSH.md

## Project Overview

This is a personal portfolio website built with Bun, React, TypeScript, and Tailwind CSS. It uses the shadcn/ui component library and serves as both a portfolio and development environment for AT Protocol-related projects. The project demonstrates modern web development practices with a focus on decentralized technologies.

## Development Commands

### Core Commands
- `bun install` - Install dependencies
- `bun dev` - Start development server with hot reload and HMR
- `bun start` - Run production server
- `bun run build.ts` - Build for production (outputs to `dist/`)
- `bun run build.ts --help` - Show all build options

### Build System
The custom build script (`build.ts`) supports various options:
- `--outdir <path>` - Output directory (default: "dist")
- `--minify` - Enable minification
- `--sourcemap <type>` - Sourcemap type (none|linked|inline|external)
- `--external <list>` - External packages (comma separated)

The build automatically:
- Processes all HTML files in `src/` as entrypoints
- Copies `public/` folder to dist
- Uses Tailwind plugin for CSS processing
- Includes linked sourcemaps by default

## Architecture

### Project Structure
```
src/
├── components/
│   ├── ui/           # shadcn/ui components (Button, Card, Input, etc.)
│   ├── sections/     # Main page sections (Header, Work, Connect)
│   └── ...           # Other React components
├── data/
│   └── portfolio.ts  # Portfolio content and metadata
├── hooks/            # Custom React hooks
├── lib/              # Utility functions
└── styles/           # Global CSS and Tailwind config
```

### Server Architecture
- Uses Bun's built-in server (`src/index.ts`)
- Serves React SPA with API routes
- API routes use pattern matching (`/api/hello/:name`)
- CORS headers configured for cross-origin requests
- Development mode includes HMR and browser console echoing

### Key Files
- `src/index.ts` - Server entry point with API routes
- `src/App.tsx` - Main React component with intersection observer animations
- `src/data/portfolio.ts` - All portfolio content (personal info, work experience, skills)
- `build.ts` - Custom build script with extensive CLI options
- `styles/globals.css` - Tailwind imports, CSS variables, and custom animations

## Code Conventions

### TypeScript Configuration
- Strict mode enabled with `noUncheckedIndexedAccess`
- Path aliases: `@/*` maps to `./src/*`
- JSX: `react-jsx` transform
- Module resolution: `bundler` mode
- Target: `ESNext` with DOM libraries

### Component Patterns
- Uses shadcn/ui component library with `class-variance-authority`
- Utility function `cn()` combines `clsx` and `tailwind-merge`
- Components follow Radix UI patterns for accessibility
- File exports: Named exports for components, default for main App

### Styling
- Tailwind CSS v4 with custom CSS variables
- Dark theme by default with light mode support
- Glassmorphism effects with custom utilities
- Custom animations: `fade-in-up`, `bounce-slow`
- Fira Code monospace font throughout

### Import Aliases (from components.json)
```typescript
"@/components" → "./src/components"
"@/lib/utils" → "./src/lib/utils"  
"@/components/ui" → "./src/components/ui"
"@/lib" → "./src/lib"
"@/hooks" → "./src/hooks"
```

## UI Components

### shadcn/ui Integration
The project uses shadcn/ui with:
- Style variant: "new-york"
- Base color: "neutral"
- Icon library: Lucide React
- CSS variables enabled
- Custom CSS location: `styles/globals.css`

### Available UI Components
- Button (multiple variants: default, destructive, outline, secondary, ghost, link)
- Card
- Input
- Label
- Select
- Textarea

### Custom Components
- ThemeToggle (dark/light mode switching)
- SectionNav (navigation between portfolio sections)
- ProjectCard/WorkExperienceCard (portfolio item displays)
- SocialLink (social media links with icons)

## Content Management

Portfolio data is centralized in `src/data/portfolio.ts`:
- `personalInfo` - Name, title, description, availability, contact
- `currentRole` - Current employment status
- `skills` - Array of technical skills
- `workExperience` - Array of work history with projects
- `socialLinks` - Social media profiles
- `sections` - Page section identifiers

The description format supports rich text with bold styling and URLs:
```typescript
type DescriptionPart = {
  text: string
  bold?: boolean
  url?: string
}
```

## Deployment

### Netlify Configuration
- Static site hosting
- CORS headers configured in `public/netlify.toml`
- AT Protocol DID file at `public/.well-known/atproto-did`

### Build Output
- Production builds output to `dist/`
- All HTML files in `src/` become entrypoints
- Public assets copied automatically
- Source maps linked for debugging

## Development Notes

### Hot Module Replacement
- Development server includes HMR
- Browser console logs echoed to server
- Automatic reloading on file changes

### Performance Features
- Intersection Observer for scroll-triggered animations
- Code splitting support in build configuration
- Minification enabled by default in production
- Lazy loading with `react` imports

### AT Protocol Integration
- Project showcases AT Protocol-related work
- Uses `atproto-ui` component library
- Bluesky and Tangled integration in portfolio

## Gotchas

### Build System
- Custom build script requires Bun runtime (not Node.js)
- HTML files in `src/` automatically become entrypoints
- Must use `--external` flag for libraries that shouldn't be bundled

### Styling
- Dark mode is default styling approach
- CSS variables are used extensively for theming
- Custom glassmorphism effects require SVG filters (defined in CSS)

### Server Routes
- API routes use Bun's pattern matching syntax
- All unmatched routes serve the main SPA (catch-all route)
- CORS headers pre-configured for API access

### Content Structure
- Portfolio content is TypeScript data, not markdown
- Rich text descriptions use specific object structure
- Projects support multiple links (live demo, GitHub, etc.)