feat(dev): add Claude Code development guidance and update gitignore

- Add comprehensive CLAUDE.md with project architecture documentation
- Include development guidelines and essential commands for AI-assisted development
- Remove CLAUDE.md from .gitignore to track development configuration
- Enable proper Claude Code CLI integration with structured project guidance

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: dietmarscharf

.gitignore

@@ -91,5 +91,4 @@ docker-data/
 data/
 docs/
 
-.claude/
-CLAUDE.md
+.claude/

CLAUDE.md

@@ -0,0 +1,108 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Claudable is a full-stack web application builder that combines AI agent capabilities with an intuitive app building experience. It allows users to generate code through natural language, with instant preview and deployment capabilities.
+
+## Essential Commands
+
+### Development
+```bash
+npm install     # Install dependencies and auto-setup (creates Python venv)
+npm run dev     # Start both frontend (port 3000) and backend (port 8080)
+```
+
+### Database Operations
+```bash
+npm run db:reset    # Reset database to initial state
+npm run db:backup   # Create database backup
+```
+
+### Cleanup
+```bash
+npm run clean      # Remove all dependencies and virtual environments
+```
+
+## Architecture Overview
+
+### Monorepo Structure
+- **apps/api/**: Python FastAPI backend with WebSocket support
+- **apps/web/**: Next.js 14 frontend with App Router
+
+### Backend Architecture (FastAPI)
+The API uses a layered architecture:
+- **app/api/**: Route handlers organized by feature (assets, chat, commits, github, projects)
+- **app/services/**: Business logic layer handling AI interactions, file operations, and external integrations
+- **app/models/**: SQLAlchemy models for database entities
+- **app/core/**: Shared utilities including WebSocket manager, crypto, and configuration
+
+Key services:
+- **ChatService**: Manages AI conversations and code generation
+- **ProjectService**: Handles project creation and management
+- **AssetService**: Manages file uploads and storage
+- **EnvironmentService**: Manages environment variables
+- **ExternalService**: Integrates with GitHub, Vercel, and Supabase
+
+### Frontend Architecture (Next.js)
+- **App Router**: Uses Next.js 14 app directory structure
+- **Component Organization**: 
+  - Common UI components in `components/ui/`
+  - Feature-specific components in respective directories
+  - Complex components like Editor, Preview, and Chat in dedicated folders
+- **State Management**: React Context (AuthContext) and local component state
+- **Real-time Communication**: WebSocket connection for chat and updates
+
+### AI Integration
+The system integrates with Claude Code CLI through:
+- System prompt at `/apps/api/app/prompt/system-prompt.md`
+- Chat service that manages conversations and code generation
+- Support for both Claude Code and Cursor CLI agents
+
+## Key Technical Details
+
+### WebSocket Communication
+- Real-time chat and updates use WebSocket protocol
+- Connection managed through `WebSocketManager` in backend
+- Frontend uses custom `useWebSocket` hook for connection handling
+
+### Authentication Flow
+- Token-based authentication using cryptography
+- Tokens stored in localStorage on frontend
+- Backend validates tokens for protected routes
+
+### File System Operations
+- Project files stored in `apps/api/data/projects/`
+- Asset uploads handled by dedicated asset service
+- Git operations performed through subprocess calls
+
+### Environment Configuration
+- Frontend env vars in `apps/web/.env.local`
+- Backend configuration through environment variables
+- Dynamic environment management UI for users
+
+## Development Guidelines
+
+### Adding New Features
+1. Backend routes go in `apps/api/app/api/`
+2. Business logic belongs in `apps/api/app/services/`
+3. Frontend pages use Next.js App Router in `apps/web/app/`
+4. Shared components go in `apps/web/components/`
+
+### Database Changes
+- Models defined in `apps/api/app/models/`
+- Database migrations handled manually
+- Use `npm run db:reset` for clean slate during development
+
+### Error Handling
+- Backend uses FastAPI's exception handling
+- Frontend displays errors through toast notifications
+- WebSocket errors trigger automatic reconnection
+
+### External Service Integration
+When adding new external services:
+1. Add service configuration in backend
+2. Create connection modal in frontend
+3. Update `ExternalService` to handle new integration
+4. Add appropriate environment variables