calchat/CLAUDE.md

CLAUDE.md

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

Project Overview

CalChat is a calendar mobile app with AI support. The core concept is creating calendar events through a chat interface with an AI chatbot (Claude). Users can add, edit, and delete events via natural language conversation.

This is a fullstack TypeScript monorepo with npm workspaces.

Commands

Root (monorepo)

npm install          # Install all dependencies for all workspaces

Client (apps/client) - Expo React Native app

npm run start -w @caldav/client        # Start Expo dev server
npm run android -w @caldav/client      # Start on Android
npm run ios -w @caldav/client          # Start on iOS
npm run web -w @caldav/client          # Start web version
npm run lint -w @caldav/client         # Run ESLint

Server (apps/server) - Express.js backend

npm run dev -w @caldav/server          # Start dev server with hot reload (tsx watch)
npm run build -w @caldav/server        # Compile TypeScript
npm run start -w @caldav/server        # Run compiled server (port 3000)

Technology Stack

Area	Technology	Purpose
Frontend	React Native	Mobile UI Framework
	Expo	Development platform
	Expo-Router	File-based routing
	NativeWind	Tailwind CSS for React Native
Backend	Express.js	Web framework
	MongoDB	Database
	Mongoose	ODM
	Claude (Anthropic)	AI/LLM for chat
	JWT	Authentication
Planned	iCalendar	Event export/import

Architecture

Workspace Structure

apps/client      - @caldav/client - Expo React Native app
apps/server      - @caldav/server - Express.js backend
packages/shared  - @caldav/shared - Shared TypeScript types and models

Frontend Architecture (apps/client)

Screens (src/app/): Login, Register, Calendar, Chat, Event Detail, Notes - file-based routing via Expo-Router

Services: API Client for HTTP requests, plus AuthService, EventService, ChatService for domain logic

Components: Reusable UI (EventCard, ChatBubble, EventConfirmDialog, MonthSelector)

Stores: AuthStore (user + token), EventsStore (calendar events)

Backend Architecture (apps/server)

src/
├── app.ts                    # Entry point, DI setup, Express config
├── controllers/              # Request handlers
│   ├── AuthController.ts     # login(), register(), refresh(), logout()
│   ├── ChatController.ts     # sendMessage(), confirmEvent(), rejectEvent(), getConversations(), getConversation()
│   └── EventController.ts    # create(), getById(), getAll(), getByDateRange(), update(), delete()
├── middleware/
│   └── AuthMiddleware.ts     # authenticate() - JWT validation
├── routes/                   # API endpoint definitions
│   ├── index.ts              # Combines all routes under /api
│   ├── auth.routes.ts        # /api/auth/*
│   ├── chat.routes.ts        # /api/chat/* (protected)
│   └── event.routes.ts       # /api/events/* (protected)
├── services/                 # Business logic
│   ├── interfaces/           # DB-agnostic interfaces (for dependency injection)
│   │   ├── AIProvider.ts     # processMessage()
│   │   ├── UserRepository.ts # + CreateUserData (server-internal DTO)
│   │   ├── EventRepository.ts
│   │   └── ChatRepository.ts
│   ├── AuthService.ts
│   ├── ChatService.ts
│   └── EventService.ts
├── repositories/             # Data access (DB-specific implementations)
│   ├── index.ts              # Re-exports from ./mongo
│   └── mongo/                # MongoDB implementation
│       ├── models/           # Mongoose schemas
│       │   ├── UserModel.ts
│       │   ├── EventModel.ts
│       │   └── ChatModel.ts
│       ├── MongoUserRepository.ts
│       ├── MongoEventRepository.ts
│       └── MongoChatRepository.ts
├── ai/
│   └── ClaudeAdapter.ts      # Implements AIProvider
└── utils/
    ├── jwt.ts                # signToken(), verifyToken()
    └── password.ts           # hash(), compare()

API Endpoints:

• POST /api/auth/login - User login
• POST /api/auth/register - User registration
• POST /api/auth/refresh - Refresh JWT token
• POST /api/auth/logout - User logout
• GET /api/events - Get all events (protected)
• GET /api/events/range - Get events by date range (protected)
• GET /api/events/:id - Get single event (protected)
• POST /api/events - Create event (protected)
• PUT /api/events/:id - Update event (protected)
• DELETE /api/events/:id - Delete event (protected)
• POST /api/chat/message - Send message to AI (protected)
• POST /api/chat/confirm/:conversationId/:messageId - Confirm proposed event (protected)
• POST /api/chat/reject/:conversationId/:messageId - Reject proposed event (protected)
• GET /api/chat/conversations - Get all conversations (protected)
• GET /api/chat/conversations/:id - Get messages of a conversation with cursor-based pagination (protected)
• GET /health - Health check

Shared Package (packages/shared)

src/
├── index.ts
└── models/
    ├── index.ts
    ├── User.ts           # User, CreateUserDTO, LoginDTO, AuthResponse
    ├── CalendarEvent.ts  # CalendarEvent, CreateEventDTO, UpdateEventDTO
    └── ChatMessage.ts    # ChatMessage, Conversation, SendMessageDTO, CreateMessageDTO,
                          # GetMessagesOptions, ChatResponse, ConversationSummary

Key Types:

• User: id, email, displayName, passwordHash?, createdAt?, updatedAt?
• CalendarEvent: id, userId, title, description?, startTime, endTime, note?, isRecurring?, recurrenceRule?
• ChatMessage: id, conversationId, sender ('user' | 'assistant'), content, proposedEvent?
• Conversation: id, userId, createdAt?, updatedAt? (messages loaded separately via lazy loading)
• CreateEventDTO: Used for creating events AND for AI-proposed events
• GetMessagesOptions: Cursor-based pagination with before?: string and limit?: number
• ConversationSummary: id, lastMessage?, createdAt? (for conversation list)

Database Abstraction

The repository pattern allows swapping databases:

• Interfaces (services/interfaces/) are DB-agnostic
• Implementations (repositories/mongo/) are DB-specific
• To add MySQL: create repositories/mysql/ with TypeORM entities

MVP Feature Scope

Must-Have

• Chat interface with AI assistant (text input) for event management
• Calendar overview
• Manual event CRUD (without AI)
• View completed events
• Simple reminders
• One note per event
• Recurring events

Nice-to-Have

• iCalendar import/export
• Multiple calendars
• CalDAV synchronization with external services

Current Implementation Status

Backend: Skeleton complete - all files exist with throw new Error('Not implemented') placeholders. Ready for step-by-step implementation.

Shared: Types and DTOs defined and exported.

Frontend: Calendar screen partially implemented, Chat screen exists but not connected to backend.

Documentation

Detailed architecture diagrams are in docs/:

• technisches_brainstorm.tex - Technical concept document (German)
• architecture-class-diagram.puml - Backend class diagram
• frontend-class-diagram.puml - Frontend class diagram
• component-diagram.puml - System component overview