This directory contains the backend logic for the Notion webhook integration application.

• controllers/ - Business logic and orchestration

  • Contains functions that validate data, orchestrate service calls, and return standardized responses
  • All controllers return {success, data, error, details?} format
  • Controllers are HTTP-agnostic (don't create HTTP responses)

• routes/ - HTTP request/response handling

  • api/ - RESTful API endpoints for data operations
  • tasks/ - Notion webhook handlers
  • views/ - User-facing HTML/React views
  • authCheck.ts - Authentication middleware

• services/ - External API integrations

  • Handle calls to external APIs (Notion, Firecrawler, blob storage, etc.)
  • Return structured results with {success, data, error} format
  • Manage API authentication and error handling

Request → Route → Controller → Service → External API

Never skip layers!

• Routes call controllers (not services directly)
• Controllers call services (not external APIs directly)
• Services handle external API calls

1. Create route in appropriate directory (api/, tasks/, or views/)
2. Create controller function with business logic
3. Create/use service functions for external API calls
4. Mount route in main.http.tsx

See CLAUDE.md for detailed guidelines.