feat: Add CLAUDE.md for project architecture and development guidance

CLAUDE.md

@@ -0,0 +1,152 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Architecture Overview
+
+Claudable is a full-stack web application that connects AI coding agents (Claude Code, Cursor CLI, etc.) with a web-based interface for building and deploying Next.js applications. The architecture consists of:
+
+### Frontend (apps/web)
+- **Next.js 14** application with TypeScript
+- **App Router** architecture with pages in `app/` directory
+- **Tailwind CSS** for styling with dark mode support
+- **Framer Motion** for animations
+- **React Context** for global state management (Auth, GlobalSettings)
+- **Component Architecture**: Shared components for project management, modals, and UI elements
+
+### Backend (apps/api) 
+- **FastAPI** Python web framework
+- **SQLAlchemy** for database operations with SQLite (local) / PostgreSQL (production)
+- **WebSocket** support for real-time communication
+- **Claude Code SDK** integration for AI agent communication
+- **Modular structure**: 
+  - `api/` - REST endpoints
+  - `core/` - Configuration and utilities
+  - `models/` - Database models
+  - `services/` - Business logic
+  - `db/` - Database connections
+
+### Key Integrations
+- **Multiple AI Agents**: Claude Code (primary), Cursor CLI, Codex CLI, Gemini CLI, Qwen Code
+- **Deployment**: Vercel integration for hosting
+- **Version Control**: GitHub integration for repositories
+- **Database**: Supabase for production PostgreSQL
+- **File Management**: Local SQLite database with project files stored in `data/`
+
+## Development Commands
+
+### Primary Development
+```bash
+# Start full development environment (both frontend and backend)
+npm run dev
+
+# Frontend only (Next.js dev server)
+npm run dev:web
+
+# Backend only (FastAPI with uvicorn) 
+npm run dev:api
+```
+
+### Database Operations
+```bash
+# Reset database to initial state (WARNING: Deletes all data)
+npm run db:reset
+
+# Create backup of SQLite database
+npm run db:backup
+
+# Restore from backup (manual operation)
+```
+
+### Environment Management
+```bash
+# Setup environment files and Python venv
+npm run setup
+
+# Clean all dependencies and environments
+npm run clean
+
+# Ensure environment is properly configured
+npm run ensure:env
+npm run ensure:venv
+```
+
+### Testing and Quality
+The project uses:
+- Next.js built-in TypeScript checking
+- FastAPI automatic OpenAPI documentation at `http://localhost:8080/docs`
+- Manual testing through web interface
+
+## Project Structure
+
+```
+Claudable/
+├── apps/
+│   ├── web/           # Next.js frontend
+│   │   ├── app/       # App Router pages
+│   │   ├── components/# Reusable React components  
+│   │   ├── contexts/  # React Context providers
+│   │   └── types/     # TypeScript type definitions
+│   └── api/           # FastAPI backend
+│       └── app/
+│           ├── api/   # REST endpoints
+│           ├── core/  # Configuration & utilities
+│           ├── models/# Database models
+│           └── services/ # Business logic
+├── scripts/           # Build and development scripts
+├── data/             # SQLite database and project files
+└── assets/          # Static assets and documentation images
+```
+
+## Configuration
+
+### Environment Setup
+Copy `.env.example` to `.env` and configure:
+
+**Required:**
+- `ANTHROPIC_API_KEY` - For Claude Code SDK integration
+
+**Optional:**
+- `API_PORT` - Backend server port (default: 8080)
+- `WEB_PORT` - Frontend server port (default: 3000) 
+- `DATABASE_URL` - PostgreSQL connection (for production)
+- Service integrations: GitHub, Vercel, Supabase tokens
+
+### Port Configuration
+The application automatically detects available ports:
+- Frontend: http://localhost:3000 (or next available)
+- Backend: http://localhost:8080 (or next available)
+- API Documentation: http://localhost:8080/docs
+
+## Development Workflow
+
+1. **Project Creation**: Users describe their app idea through the web interface
+2. **AI Agent Selection**: Choose from Claude Code, Cursor CLI, Codex CLI, Gemini CLI, or Qwen Code
+3. **Code Generation**: Selected AI agent generates Next.js application code
+4. **Live Preview**: Real-time preview with hot-reload during development
+5. **Deployment**: One-click deployment to Vercel with GitHub integration
+
+## Key Features Implementation
+
+### Multi-Agent Support
+- Agent detection and installation checking via `scripts/` utilities
+- Per-project agent preference stored in database
+- Model selection per agent (GPT-5, Claude Sonnet 4, etc.)
+
+### Real-time Communication  
+- WebSocket connection between frontend and backend
+- Live code generation updates
+- Preview server management
+
+### Project Management
+- SQLite database for local development
+- Project files stored in `data/projects/`
+- Preview servers run on dynamic port allocation
+- Automatic cleanup and resource management
+
+## Development Tips
+
+- Backend API documentation is auto-generated at `/docs` endpoint
+- Frontend builds use Next.js with Turbo for faster compilation
+- Database schema changes require manual migration planning
+- All AI agent communication goes through the Claude Code SDK wrapper

README.md

@@ -1,15 +1,21 @@
 # Claudable
 
-<img src="./assets/Claudable_main.png" alt="CLovable" style="border-radius: 12px; width: 100%;" />
+<img src="./assets/Claudable.png" alt="Claudable" style="width: 100%;" />
 <div align="center">
-<h3>Connect Claude Code. Build what you want. Deploy instantly.</h3>
+<h3>Connect CLI Agent • Build what you want • Deploy instantly</h3>
 
 <p>Powered by <a href="https://opactor.ai">OPACTOR</a></p>
 </div>
 <p align="center">
 <a href="https://discord.gg/NJNbafHNQC">
 <img src="https://img.shields.io/badge/Discord-Join%20Community-7289da?style=flat&logo=discord&logoColor=white" alt="Join Discord Community">
 </a>
+<a href="https://opactor.ai">
+<img src="https://img.shields.io/badge/OPACTOR-Website-000000?style=flat&logo=web&logoColor=white" alt="OPACTOR Website">
+</a>
+<a href="https://twitter.com/aaron_xong">
+<img src="https://img.shields.io/badge/Follow-@aaron__xong-000000?style=flat&logo=x&logoColor=white" alt="Follow Aaron">
+</a>
 </p>
 
 ## What is Claudable?
@@ -21,7 +27,7 @@ This open-source project empowers you to build and deploy professional web appli
 How to start? Simply login to Claude Code (or Cursor CLI), start Claudable, and describe what you want to build. That's it. There is no additional subscription cost for app builder. 
 
 ## Features
-<img src="./assets/Claudable_short.gif" alt="Claudable Demo" style="width: 100%; max-width: 800px;">
+<img src="./assets/gif/Claudable_v2_cc_4_1080p.gif" alt="Claudable Demo" style="width: 100%; max-width: 800px;">
 
 - **Powerful Agent Performance**: Leverage the full power of Claude Code and Cursor CLI Agent capabilities with native MCP support
 - **Natural Language to Code**: Simply describe what you want to build, and Claudable generates production-ready Next.js code
@@ -33,23 +39,81 @@ How to start? Simply login to Claude Code (or Cursor CLI), start Claudable, and
 - **Supabase Database**: Connect production PostgreSQL with authentication ready to use
 - **Automated Error Detection**: Detect errors in your app and fix them automatically
 
-## Technology Stack
-**AI Cooding Agent:**
-- **[Claude Code](https://docs.anthropic.com/en/docs/claude-code/setup)**: Advanced AI coding agent. We strongly recommend you to use Claude Code for the best experience.
+## Demo Examples
+
+### Codex CLI Example
+<img src="./assets/gif/Claudable_v2_codex_1_1080p.gif" alt="Codex CLI Demo" style="width: 100%; max-width: 800px;">
+
+### Qwen Code Example
+<img src="./assets/gif/Claudable_v2_qwen_1_1080p.gif" alt="Qwen Code Demo" style="width: 100%; max-width: 800px;">
+
+## Supported AI Coding Agents
+
+Claudable supports multiple AI coding agents, giving you the flexibility to choose the best tool for your needs:
+
+- **Claude Code** - Anthropic's advanced AI coding agent
+- **Codex CLI** - OpenAI's lightweight coding agent
+- **Cursor CLI** - Powerful multi-model AI agent
+- **Gemini CLI** - Google's open-source AI agent
+- **Qwen Code** - Alibaba's open-source coding CLI
+
+### Claude Code (Recommended)
+**[Claude Code](https://docs.anthropic.com/en/docs/claude-code/setup)** - Anthropic's advanced AI coding agent with Claude Opus 4.1
+- **Features**: Deep codebase awareness, MCP support, Unix philosophy, direct terminal integration
+- **Context**: Native 256K tokens
+- **Pricing**: Included with ChatGPT Plus/Pro/Team/Edu/Enterprise plans
+- **Installation**:
   ```bash
-  # Install
   npm install -g @anthropic-ai/claude-code
-  # Login
   claude  # then > /login
   ```
-- **[Cursor CLI](https://docs.cursor.com/en/cli/overview)**: Intelligent coding agent for complex coding tasks. It's little bit slower than Claude Code, but it's more powerful.
+
+### Codex CLI
+**[Codex CLI](https://github.com/openai/codex)** - OpenAI's lightweight coding agent with GPT-5 support
+- **Features**: High reasoning capabilities, local execution, multiple operating modes (interactive, auto-edit, full-auto)
+- **Context**: Varies by model
+- **Pricing**: Included with ChatGPT Plus/Pro/Business/Edu/Enterprise plans
+- **Installation**:
+  ```bash
+  npm install -g @openai/codex
+  codex  # login with ChatGPT account
+  ```
+
+### Cursor CLI
+**[Cursor CLI](https://cursor.com/en/cli)** - Powerful AI agent with access to cutting-edge models
+- **Features**: Multi-model support (Anthropic, OpenAI, Gemini), MCP integration, AGENTS.md support
+- **Context**: Model dependent
+- **Pricing**: Free tier available, Pro plans for advanced features
+- **Installation**:
   ```bash
-  # Install
   curl https://cursor.com/install -fsS | bash
-  # Login
   cursor-agent login
   ```
 
+### Gemini CLI
+**[Gemini CLI](https://developers.google.com/gemini-code-assist/docs/gemini-cli)** - Google's open-source AI agent with Gemini 2.5 Pro
+- **Features**: 1M token context window, Google Search grounding, MCP support, extensible architecture
+- **Context**: 1M tokens (with free tier: 60 req/min, 1000 req/day)
+- **Pricing**: Free with Google account, paid tiers for higher limits
+- **Installation**:
+  ```bash
+  npm install -g @google/gemini-cli
+  gemini  # follow authentication flow
+  ```
+
+### Qwen Code
+**[Qwen Code](https://github.com/QwenLM/qwen-code)** - Alibaba's open-source CLI for Qwen3-Coder models
+- **Features**: 256K-1M token context, multiple model sizes (0.5B to 480B), Apache 2.0 license
+- **Context**: 256K native, 1M with extrapolation
+- **Pricing**: Completely free and open-source
+- **Installation**:
+  ```bash
+  npm install -g @qwen-code/qwen-code@latest
+  qwen --version
+  ```
+
+## Technology Stack
+
 **Database & Deployment:**
 - **[Supabase](https://supabase.com/)**: Connect production-ready PostgreSQL database directly to your project.
 - **[Vercel](https://vercel.com/)**: Publish your work immediately with one-click deployment
@@ -208,20 +272,22 @@ If you encounter the error: `Error output dangerously skip permissions cannot be
 - Anon Key: Public key for client-side
 - Service Role Key: Secret key for server-side
 
-## Design Comparison
 
-*Same prompt, different results*
-
-### Claudable
-<img src="./assets/Claudable_ex.png" alt="Claudable Design" style="border-radius: 12px; width: 100%;" />
+## License
 
-[View Claudable Live Demo →](https://claudable-preview.vercel.app/)
+MIT License.
 
-### Lovable
-<img src="./assets/Lovable_ex.png" alt="Lovable Design" style="border-radius: 12px; width: 100%;" />
+## Upcoming Features
+These features are in development and will be opened soon.
+- **New CLI Agents** - Trust us, you're going to LOVE this!
+- **Checkpoints for Chat** - Save and restore conversation/codebase states
+- **Advanced MCP Integration** - Native integration with MCP
+- **Enhanced Agent System** - Subagents, AGENTS.md integration
+- **Website Cloning** - You can start a project from a reference URL.
+- Various bug fixes and community PR merges
 
-[View Lovable Live Demo →](https://preview--goal-track-studio.lovable.app/)
+We're working hard to deliver the features you've been asking for. Stay tuned!
 
-## License
+## Star History
 
-MIT License.
+[![Star History Chart](https://api.star-history.com/svg?repos=opactorai/Claudable&type=Date)](https://www.star-history.com/#opactorai/Claudable&Date)

apps/api/app/api/assets.py

@@ -28,6 +28,27 @@ async def upload_logo(project_id: str, body: LogoRequest, db: Session = Depends(
     return {"path": f"assets/logo.png"}
 
 
+@router.get("/{project_id}/{filename}")
+async def get_image(project_id: str, filename: str, db: Session = Depends(get_db)):
+    """Get an image file from project assets directory"""
+    from fastapi.responses import FileResponse
+
+    # Verify project exists
+    row = db.get(ProjectModel, project_id)
+    if not row:
+        raise HTTPException(status_code=404, detail="Project not found")
+
+    # Build file path
+    file_path = os.path.join(settings.projects_root, project_id, "assets", filename)
+
+    # Check if file exists
+    if not os.path.exists(file_path):
+        raise HTTPException(status_code=404, detail="Image not found")
+
+    # Return the image file
+    return FileResponse(file_path)
+
+
 @router.post("/{project_id}/upload")
 async def upload_image(project_id: str, file: UploadFile = File(...), db: Session = Depends(get_db)):
     """Upload an image file to project assets directory"""