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

This is a Val Town project. It's a full-stack application with a React frontend and a Hono-based API backend, designed to run on Val Town's Deno serverless platform.

├── backend/
│   ├── controllers/         # Business logic controllers
│   ├── routes/             # Route definitions and HTTP handling
│   │   ├── api/            # API endpoints
│   │   ├── tasks/          # Task-related routes; commonly, Notion webhooks
│   │   ├── views/          # User-facing views
│   │   └── authCheck.ts    # Authentication middleware
│   └── services/           # External service integrations
├── frontend/               # React frontend assets
│   ├── index.html        # HTML template for glimpse views
│   ├── index.tsx         # React entry point
│   ├── components/         # React components
│   │   ├── App.tsx       # Main display component
│   │   ├── NotionBlock.tsx # Notion block renderer
│   │   └── NotionProperty.tsx # Property display component
│   └── README.md
├── shared/                 # Shared utilities and types
│   ├── types.ts           # TypeScript interfaces for Notion data
│   ├── utils.ts           # Shared utility functions
│   └── README.md
└── main.http.tsx               # Application entry point with static file serving

The application follows a clean MVC architecture with proper separation of concerns:

• Handles HTTP request/response formatting
• Extracts parameters from requests
• Applies authentication middleware
• Calls controller functions and formats responses
• Manages HTTP status codes and error responses

• Contains business logic and orchestrates service calls
• Returns plain data objects (not HTTP responses)
• Handles data validation and transformation
• Filters sensitive data (e.g., button properties)
• Provides consistent success/error response structure

• Handles external API calls (Notion, Notion databases, Notion pages, Firecrawler, val.town's blob storage, etc)
• Manages data persistence
• Returns structured results with success/error information

All controller functions return a consistent structure:

{
  success: boolean,
  data: any | null,
  error: string | null,
  details?: string  // Additional error context
}

Routes then format these into appropriate HTTP responses.

• main.http.tsx is the main HTTP entry point that exports app.fetch for Val Town
• Uses Hono for routing and middleware
• Serves static frontend assets and mounts API routes at /api

• React 18.2.0 single-page application
• index.html: Minimal HTML shell that loads the React app
• index.tsx: React app entry point
• components/App.tsx: Main app component with state management for email processing

All React components use /** @jsxImportSource https://esm.sh/react@18.2.0 */ and pin React dependencies to version 18.2.0.

Since this is a Val Town project, there are no local build commands. The application runs directly on Val Town when deployed.

Required environment variables are set in Val Town.

TODO: add note about how to access env vars

Uses Val Town's standard utilities for serving project files:

Create val
import {
  readFile,
  serveFile,
} from "https://esm.town/v/std/utils@85-main/index.ts";

Frontend files are served through Hono:

• /frontend/* routes serve frontend assets with proper content types
• / route serves the main index.html

All React files must:

1. Include /** @jsxImportSource https://esm.sh/react@18.2.0 */ at the top
2. Import React dependencies with pinned version: ?deps=react@18.2.0
3. Use React 18.2.0 consistently across all dependencies

The API routes use try-catch blocks and return appropriate HTTP status codes (400 for validation errors, 500 for server errors). Consider adding a Hono error handler to unwrap and re-throw errors for better stack traces.

• deno.json: Deno configuration with Val Town types, compiler options, and experimental features
  • Disables strict TypeScript checking
  • Includes Val Town type definitions
  • Enables Deno unstable features (node globals, temporal, worker options, sloppy imports)
• AGENTS.md: Comprehensive Val Town development guidelines (keep this file as reference for Val Town best practices)