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

# Check types
deno check src/**/*.ts src/**/*.tsx

Architecture Overview#

This is a Deno-based web application built with the Slices CLI. It provides server-side rendering with Preact, OAuth authentication, and AT Protocol integration for building applications on the decentralized web.

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 PKCE flow using @slices/oauth
• Sessions: SQLite-based with @slices/session
• Database: SQLite via OAuth and session libraries

Core Architecture Patterns#

Feature-Based Organization#

The codebase is organized by features rather than technical layers:

src/
├── features/           # Feature modules
│   └── auth/          # Authentication (login/logout)
├── shared/            # Shared UI components
├── routes/            # Route definitions and middleware
├── utils/             # Utility functions
└── config.ts          # Core configuration

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
• PKCE flow for secure authentication
• Session management with @slices/session
• SQLite storage for OAuth state and sessions
• 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

OAuth Integration#

• src/config.ts - OAuth client and session store setup
• Environment variables required: OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, OAUTH_REDIRECT_URI, OAUTH_AIP_BASE_URL, API_URL, SLICE_URI
• PKCE flow implementation in auth handlers
• SQLite storage for OAuth state and tokens

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 auth middleware

Environment Setup#

The application requires a .env file with OAuth and API configuration. Copy .env.example and fill in your values. 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

OAuth Flow#

1. User initiates login with handle/identifier
2. OAuth client generates PKCE challenge and redirects to auth server
3. User authenticates and is redirected back with authorization code
4. Client exchanges code for tokens using PKCE verifier
5. Session created with automatic token refresh
6. Protected routes access user data through authenticated client

Adding New Features#

To add a new feature:

1. Create src/features/feature-name/
2. Add handlers.tsx with route handlers
3. Create templates/ directory for UI components
4. Export routes and add to main router
5. Use existing patterns for authentication and rendering