CLAUDE.md#

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

Development Commands#

# 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