# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with
code in this repository.

## Development Commands

```bash
# Start development server with hot reload
deno task dev

# Start production server  
deno task start

# Format code
deno fmt

# Run tests
deno test
```

## Architecture Overview

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.

### Technology Stack

- **Runtime**: Deno with TypeScript
- **Frontend**: Preact with server-side rendering
- **Styling**: Tailwind CSS (via CDN)
- **Interactivity**: HTMX + Hyperscript
- **Routing**: Deno's standard HTTP routing
- **Authentication**: OAuth with AT Protocol integration
- **Database**: SQLite via `@slices/oauth` and `@slices/session`

### Core Architecture Patterns

#### Feature-Based Organization

The codebase is organized by features rather than technical layers:

```
src/
├── features/           # Feature modules
│   ├── auth/          # Authentication (login/logout)
│   ├── dashboard/     # Main dashboard (slice management)  
│   ├── settings/      # User settings
│   └── slices/        # Slice-specific features
│       ├── overview/  # Slice overview
│       ├── lexicon/   # AT Protocol lexicon management
│       ├── records/   # Record browsing/filtering
│       ├── oauth/     # OAuth client management
│       ├── codegen/   # TypeScript client generation
│       ├── sync/      # Data synchronization
│       ├── jetstream/ # Real-time streaming
│       └── api-docs/  # API documentation
├── shared/            # Shared UI components
├── routes/            # Route definitions and middleware
├── utils/             # Utility functions
└── lib/               # Core libraries
```

#### Handler Pattern

Each feature follows a consistent pattern:

- `handlers.tsx` - Route handlers that return Response objects
- `templates/` - Preact components for rendering
- `templates/fragments/` - Reusable UI components

#### Authentication & Sessions

- OAuth integration with AT Protocol using `@slices/oauth`
- Session management with `@slices/session`
- Authentication state managed via `withAuth()` middleware
- Automatic token refresh capabilities

### Key Components

#### Route System

- All routes defined in `src/routes/mod.ts`
- Feature routes exported from `src/features/*/handlers.tsx`
- Middleware in `src/routes/middleware.ts` handles auth state

#### Client Integration

- `src/client.ts` - Generated AT Protocol client for API communication
- `src/config.ts` - Centralized configuration and service setup
- Environment variables required: `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`,
  `OAUTH_REDIRECT_URI`, `OAUTH_AIP_BASE_URL`, `API_URL`, `SLICE_URI`
- Optional variables: `DOCS_PATH` (path to markdown documentation files,
  defaults to "../docs")

#### Rendering System

- `src/utils/render.tsx` - Unified HTML rendering with proper headers
- Server-side rendering with Preact
- HTMX for dynamic interactions without page reloads
- Shared `Layout` component in `src/shared/fragments/Layout.tsx`

### Development Guidelines

#### Component Conventions

- Use `.tsx` extension for components with JSX
- Preact components for all UI rendering
- HTMX attributes for interactive behavior
- Tailwind classes for styling

#### Feature Development

When adding new features:

1. Create feature directory under `src/features/`
2. Add `handlers.tsx` with route definitions
3. Create `templates/` directory with Preact components
4. Export routes from feature and add to `src/routes/mod.ts`
5. Follow existing authentication patterns using `withAuth()`

#### Environment Setup

The application requires a `.env` file with OAuth and API configuration. Missing
environment variables will cause startup failures with descriptive error
messages.

### Request/Response Flow

1. Request hits main server in `src/main.ts`
2. Routes processed through `src/routes/mod.ts`
3. Authentication middleware applies session state
4. Feature handlers process requests and return rendered HTML
5. HTMX handles partial page updates on client-side interactions