Linus Waldowsky
105a9a4980
- Add AuthController login/register endpoints with error handling - Implement AuthService with password validation and user creation - Add MongoUserRepository with findByEmail and create methods - Implement password hashing with bcrypt - Add dotenv for environment variable support - Add Docker Compose setup for MongoDB + Mongo Express - Stub AuthMiddleware with fake user for testing - Update CLAUDE.md with implementation status
259 lines
11 KiB
Markdown
259 lines
11 KiB
Markdown
# 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)
|
|
```bash
|
|
npm install # Install all dependencies for all workspaces
|
|
```
|
|
|
|
### Client (apps/client) - Expo React Native app
|
|
```bash
|
|
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
|
|
```bash
|
|
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 |
|
|
| | Zustand | State management |
|
|
| | FlashList | High-performance lists |
|
|
| 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)
|
|
|
|
```
|
|
src/
|
|
├── app/ # Expo-Router file-based routing
|
|
│ ├── _layout.tsx # Root Stack layout
|
|
│ ├── index.tsx # Entry redirect
|
|
│ ├── login.tsx # Login screen
|
|
│ ├── register.tsx # Registration screen
|
|
│ ├── (tabs)/ # Tab navigation group
|
|
│ │ ├── _layout.tsx # Tab bar configuration
|
|
│ │ ├── chat.tsx # Chat screen (AI conversation)
|
|
│ │ └── calendar.tsx # Calendar overview
|
|
│ ├── event/
|
|
│ │ └── [id].tsx # Event detail screen (dynamic route)
|
|
│ └── note/
|
|
│ └── [id].tsx # Note editor for event (dynamic route)
|
|
├── components/
|
|
│ ├── BaseBackground.tsx # Common screen wrapper
|
|
│ ├── Header.tsx # Header component
|
|
│ ├── EventCard.tsx # Event card for calendar display
|
|
│ └── EventConfirmDialog.tsx # AI-proposed event confirmation modal
|
|
├── services/
|
|
│ ├── index.ts # Re-exports all services
|
|
│ ├── ApiClient.ts # HTTP client (get, post, put, delete)
|
|
│ ├── AuthService.ts # login(), register(), logout(), refresh()
|
|
│ ├── EventService.ts # getAll(), getById(), getByDateRange(), create(), update(), delete()
|
|
│ └── ChatService.ts # sendMessage(), confirmEvent(), rejectEvent(), getConversations(), getConversation()
|
|
└── stores/ # Zustand state management
|
|
├── index.ts # Re-exports all stores
|
|
├── AuthStore.ts # user, token, isAuthenticated, login(), logout(), setToken()
|
|
└── EventsStore.ts # events[], setEvents(), addEvent(), updateEvent(), deleteEvent()
|
|
```
|
|
|
|
**Routing:** Tab-based navigation with Chat and Calendar as main screens. Auth screens (login, register) outside tabs. Dynamic routes for event detail and note editing.
|
|
|
|
### 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
|
|
|
|
## Development Environment
|
|
|
|
### MongoDB (Docker)
|
|
```bash
|
|
cd apps/server/docker/mongo
|
|
docker compose up -d # Start MongoDB + Mongo Express
|
|
docker compose down # Stop services
|
|
```
|
|
- MongoDB: `localhost:27017` (root/mongoose)
|
|
- Mongo Express UI: `localhost:8081` (admin/admin)
|
|
|
|
### Environment Variables
|
|
Server requires `.env` file in `apps/server/`:
|
|
```
|
|
JWT_SECRET=your-secret-key
|
|
JWT_EXPIRES_IN=1h
|
|
MONGODB_URI=mongodb://root:mongoose@localhost:27017/calchat?authSource=admin
|
|
```
|
|
|
|
## Current Implementation Status
|
|
|
|
**Backend:**
|
|
- **Implemented:**
|
|
- `AuthController`: login(), register() with error handling
|
|
- `AuthService`: login(), register() with password validation
|
|
- `MongoUserRepository`: findByEmail(), create()
|
|
- `utils/password`: hash(), compare() using bcrypt
|
|
- `utils/jwt`: signToken() (verifyToken() pending)
|
|
- `dotenv` integration for environment variables
|
|
- **Stubbed (TODO):**
|
|
- `AuthMiddleware.authenticate()`: Currently uses fake user for testing
|
|
- `AuthController`: refresh(), logout()
|
|
- `AuthService`: refreshToken()
|
|
- All Chat and Event functionality
|
|
- **Not started:**
|
|
- `ChatController`, `ChatService`, `MongoChatRepository`
|
|
- `EventController`, `EventService`, `MongoEventRepository`
|
|
- `ClaudeAdapter` (AI integration)
|
|
|
|
**Shared:** Types and DTOs defined and exported.
|
|
|
|
**Frontend:** Skeleton complete with file-based routing structure:
|
|
- Tab navigation (Chat, Calendar) implemented with basic UI
|
|
- Calendar screen has month navigation and grid display (partially functional)
|
|
- Chat screen has message list UI with FlashList (mock data only)
|
|
- Auth screens (Login, Register), Event Detail, and Note screens exist as skeletons
|
|
- Services (ApiClient, AuthService, EventService, ChatService) defined with `throw new Error('Not implemented')`
|
|
- Zustand stores (AuthStore, EventsStore) defined with `throw new Error('Not implemented')`
|
|
- Components (EventCard, EventConfirmDialog) exist as skeletons
|
|
|
|
## Documentation
|
|
|
|
Detailed architecture diagrams are in `docs/`:
|
|
- `api-routes.md` - API endpoint overview (German)
|
|
- `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
|