···11-- dont use any
22-- use htmx and hyperscript when possible
33-- if jsx param is true don't pass the attribute value
11+# CLAUDE.md
22+33+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
44+55+## Development Commands
66+77+```bash
88+# Start development server with hot reload
99+deno task dev
1010+1111+# Start production server
1212+deno task start
1313+1414+# Format code
1515+deno fmt
1616+1717+# Run tests
1818+deno test
1919+```
2020+2121+## Architecture Overview
2222+2323+This is a Deno-based web application that serves as the frontend for a "Slices" platform - an AT Protocol record management system. The application follows a feature-based architecture with server-side rendering using Preact and HTMX for interactivity.
2424+2525+### Technology Stack
2626+- **Runtime**: Deno with TypeScript
2727+- **Frontend**: Preact with server-side rendering
2828+- **Styling**: Tailwind CSS (via CDN)
2929+- **Interactivity**: HTMX + Hyperscript
3030+- **Routing**: Deno's standard HTTP routing
3131+- **Authentication**: OAuth with AT Protocol integration
3232+- **Database**: SQLite via `@slices/oauth` and `@slices/session`
3333+3434+### Core Architecture Patterns
3535+3636+#### Feature-Based Organization
3737+The codebase is organized by features rather than technical layers:
3838+3939+```
4040+src/
4141+├── features/ # Feature modules
4242+│ ├── auth/ # Authentication (login/logout)
4343+│ ├── dashboard/ # Main dashboard (slice management)
4444+│ ├── settings/ # User settings
4545+│ └── slices/ # Slice-specific features
4646+│ ├── overview/ # Slice overview
4747+│ ├── lexicon/ # AT Protocol lexicon management
4848+│ ├── records/ # Record browsing/filtering
4949+│ ├── oauth/ # OAuth client management
5050+│ ├── codegen/ # TypeScript client generation
5151+│ ├── sync/ # Data synchronization
5252+│ ├── jetstream/ # Real-time streaming
5353+│ └── api-docs/ # API documentation
5454+├── shared/ # Shared UI components
5555+├── routes/ # Route definitions and middleware
5656+├── utils/ # Utility functions
5757+└── lib/ # Core libraries
5858+```
5959+6060+#### Handler Pattern
6161+Each feature follows a consistent pattern:
6262+- `handlers.tsx` - Route handlers that return Response objects
6363+- `templates/` - Preact components for rendering
6464+- `templates/fragments/` - Reusable UI components
6565+6666+#### Authentication & Sessions
6767+- OAuth integration with AT Protocol using `@slices/oauth`
6868+- Session management with `@slices/session`
6969+- Authentication state managed via `withAuth()` middleware
7070+- Automatic token refresh capabilities
7171+7272+### Key Components
7373+7474+#### Route System
7575+- All routes defined in `src/routes/mod.ts`
7676+- Feature routes exported from `src/features/*/handlers.tsx`
7777+- Middleware in `src/routes/middleware.ts` handles auth state
7878+7979+#### Client Integration
8080+- `src/client.ts` - Generated AT Protocol client for API communication
8181+- `src/config.ts` - Centralized configuration and service setup
8282+- Environment variables required: `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, `OAUTH_REDIRECT_URI`, `OAUTH_AIP_BASE_URL`, `API_URL`, `SLICE_URI`
8383+8484+#### Rendering System
8585+- `src/utils/render.tsx` - Unified HTML rendering with proper headers
8686+- Server-side rendering with Preact
8787+- HTMX for dynamic interactions without page reloads
8888+- Shared `Layout` component in `src/shared/fragments/Layout.tsx`
8989+9090+### Development Guidelines
9191+9292+#### Component Conventions
9393+- Use `.tsx` extension for components with JSX
9494+- Preact components for all UI rendering
9595+- HTMX attributes for interactive behavior
9696+- Tailwind classes for styling
9797+9898+#### Feature Development
9999+When adding new features:
100100+1. Create feature directory under `src/features/`
101101+2. Add `handlers.tsx` with route definitions
102102+3. Create `templates/` directory with Preact components
103103+4. Export routes from feature and add to `src/routes/mod.ts`
104104+5. Follow existing authentication patterns using `withAuth()`
105105+106106+#### Environment Setup
107107+The application requires a `.env` file with OAuth and API configuration. Missing environment variables will cause startup failures with descriptive error messages.
108108+109109+### Request/Response Flow
110110+1. Request hits main server in `src/main.ts`
111111+2. Routes processed through `src/routes/mod.ts`
112112+3. Authentication middleware applies session state
113113+4. Feature handlers process requests and return rendered HTML
114114+5. HTMX handles partial page updates on client-side interactions