Scheduler is a Next.js application for managing calendar connections, availability, and bookings. It stores data in a local SQLite database and integrates with CalDAV providers for calendar access.

Simply run the development server, and the setup validation will guide you through any missing requirements:

pnpm install
pnpm dev

The validation script will automatically:

• Check for required environment variables and offer to generate them
• Verify database health and offer to create/recreate it if needed
• Guide you through the setup process with user-friendly prompts

If you prefer to set up manually or need to troubleshoot:

pnpm install

Create a .env.local file with required environment variables:

# Generate environment variables with secure defaults
pnpm env:generate

# Copy the generated .env.example to .env.local
cp .env.example .env.local

Required variables:

• ENCRYPTION_KEY: 64-character hex string for encrypting sensitive data
• WEBHOOK_SECRET: 32+ character secret for webhook verification

Optional variables:

• SQLITE_PATH: Database path (default: scheduler.db)
• NODE_ENV: Environment mode (default: development)
• GOOGLE_OAUTH_CLIENT_ID: Google OAuth client ID for calendar integration
• GOOGLE_OAUTH_CLIENT_SECRET: Google OAuth client secret for calendar integration

📖 See Environment Variables Documentation for detailed setup instructions.

Run once to create scheduler.db:

pnpm db:init

pnpm dev

Then open http://localhost:3000.

• app/: Next.js server and client components, organized by feature domains.
• components/: Shared UI components and feature-specific client components.
• infrastructure/: Database access, encryption utilities, and provider integrations.
• lib/: Miscellaneous shared helpers and validation.
• docs/: Architecture Decision Records (ADRs) and development guidelines.

Server actions now throw Error objects on failure. Client components should catch these and display a user-friendly message using helpers from lib/errors.ts.

For detailed information about architectural decisions, patterns, and development guidelines, see:

• Architecture Overview: Complete guide to the application architecture
• Architecture Decision Records: Documented decisions about state management, server actions, dependencies, and more
• Development Guidelines: Guidelines for maintaining simplicity and consistency
• Feature Development: Patterns for developing new features
• Feature Template: Template for creating new features
• Environment Variables: Environment setup and configuration guide

• Manual State Management: Using React hooks instead of state management libraries
• Server Actions: Direct server-side operations without API routes
• Feature-based Organization: Code organized by business domain
• Minimal Dependencies: Careful evaluation of new dependencies
• In-memory Solutions: Simple caching and rate limiting without external services

Errors related to calendar connections or encryption extend CalendarConnectionError or EncryptionError. These classes include a code field to allow mapping to descriptive messages. When an action fails, the error is caught and converted to a message for the UI using mapErrorToUserMessage.

The application follows a consistent feature-based organization pattern. Each feature has clear separation between server and client code:

• Server code (_server/): Actions, data fetching, server-only utilities
• Client code (_components/, _hooks/): Interactive components and client-side state
• Schemas (/lib/schemas/): Centralized data validation and types

📖 See Feature Organization Documentation for detailed architecture guidelines.

This project enforces strict code quality standards that must be met before any commit:

• TypeScript compilation: All code must compile without errors
• ESLint: All linting rules must pass (includes custom performance and architectural rules)
• Tests: All tests must pass (281 tests currently)
• Formatting: Code must be formatted consistently with Prettier

A pre-commit hook automatically runs all quality checks. To run them manually:

pnpm pre-commit

📖 See Code Quality Documentation for detailed requirements and workflow.