Highly ambitious ATProtocol AppView service and sdks
slices.network
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with
4code in this repository.
5
6## Development Commands
7
8```bash
9# Start development server with hot reload
10deno task dev
11
12# Start production server
13deno task start
14
15# Format code
16deno fmt
17
18# Run tests
19deno test
20```
21
22## Architecture Overview
23
24This is a Deno-based web application that serves as the frontend for a "Slices"
25platform - an AT Protocol record management system. The application follows a
26feature-based architecture with server-side rendering using Preact and HTMX for
27interactivity.
28
29### Technology Stack
30
31- **Runtime**: Deno with TypeScript
32- **Frontend**: Preact with server-side rendering
33- **Styling**: Tailwind CSS (via CDN)
34- **Interactivity**: HTMX + Hyperscript
35- **Routing**: Deno's standard HTTP routing
36- **Authentication**: OAuth with AT Protocol integration
37- **Database**: SQLite via `@slices/oauth` and `@slices/session`
38
39### Core Architecture Patterns
40
41#### Feature-Based Organization
42
43The codebase is organized by features rather than technical layers:
44
45```
46src/
47├── features/ # Feature modules
48│ ├── auth/ # Authentication (login/logout)
49│ ├── dashboard/ # Main dashboard (slice management)
50│ ├── settings/ # User settings
51│ └── slices/ # Slice-specific features
52│ ├── overview/ # Slice overview
53│ ├── lexicon/ # AT Protocol lexicon management
54│ ├── records/ # Record browsing/filtering
55│ ├── oauth/ # OAuth client management
56│ ├── codegen/ # TypeScript client generation
57│ ├── sync/ # Data synchronization
58│ ├── jetstream/ # Real-time streaming
59│ └── api-docs/ # API documentation
60├── shared/ # Shared UI components
61├── routes/ # Route definitions and middleware
62├── utils/ # Utility functions
63└── lib/ # Core libraries
64```
65
66#### Handler Pattern
67
68Each feature follows a consistent pattern:
69
70- `handlers.tsx` - Route handlers that return Response objects
71- `templates/` - Preact components for rendering
72- `templates/fragments/` - Reusable UI components
73
74#### Authentication & Sessions
75
76- OAuth integration with AT Protocol using `@slices/oauth`
77- Session management with `@slices/session`
78- Authentication state managed via `withAuth()` middleware
79- Automatic token refresh capabilities
80
81### Key Components
82
83#### Route System
84
85- All routes defined in `src/routes/mod.ts`
86- Feature routes exported from `src/features/*/handlers.tsx`
87- Middleware in `src/routes/middleware.ts` handles auth state
88
89#### Client Integration
90
91- `src/client.ts` - Generated AT Protocol client for API communication
92- `src/config.ts` - Centralized configuration and service setup
93- Environment variables required: `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`,
94 `OAUTH_REDIRECT_URI`, `OAUTH_AIP_BASE_URL`, `API_URL`, `SLICE_URI`
95- Optional variables: `DOCS_PATH` (path to markdown documentation files,
96 defaults to "../docs")
97
98#### Rendering System
99
100- `src/utils/render.tsx` - Unified HTML rendering with proper headers
101- Server-side rendering with Preact
102- HTMX for dynamic interactions without page reloads
103- Shared `Layout` component in `src/shared/fragments/Layout.tsx`
104
105### Development Guidelines
106
107#### Component Conventions
108
109- Use `.tsx` extension for components with JSX
110- Preact components for all UI rendering
111- HTMX attributes for interactive behavior
112- Tailwind classes for styling
113
114#### Feature Development
115
116When adding new features:
117
1181. Create feature directory under `src/features/`
1192. Add `handlers.tsx` with route definitions
1203. Create `templates/` directory with Preact components
1214. Export routes from feature and add to `src/routes/mod.ts`
1225. Follow existing authentication patterns using `withAuth()`
123
124#### Environment Setup
125
126The application requires a `.env` file with OAuth and API configuration. Missing
127environment variables will cause startup failures with descriptive error
128messages.
129
130### Request/Response Flow
131
1321. Request hits main server in `src/main.ts`
1332. Routes processed through `src/routes/mod.ts`
1343. Authentication middleware applies session state
1354. Feature handlers process requests and return rendered HTML
1365. HTMX handles partial page updates on client-side interactions