125 lines
4.3 KiB
Markdown
125 lines
4.3 KiB
Markdown
|
# CLAUDE.md
|
||
|
|
|
||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
|
|
||
|
|
## Project Overview
|
||
|
|
|
||
|
|
This is the **AI Bulk Image Renamer** SaaS - a web application that allows users to rename multiple images in batches using AI-generated keywords and computer vision tags. The goal is to create SEO-friendly, filesystem-safe, and semantically descriptive filenames.
|
||
|
|
|
||
|
|
### MVP Requirements (From README.md:22-31)
|
||
|
|
- Single landing page with upload functionality
|
||
|
|
- User-supplied keywords for filename generation
|
||
|
|
- "Enhance with AI" button to expand keyword lists
|
||
|
|
- Image thumbnails display after upload
|
||
|
|
- Generated filenames shown beneath corresponding images
|
||
|
|
- Download as ZIP functionality for renamed images
|
||
|
|
|
||
|
|
## Architecture & Tech Stack
|
||
|
|
|
||
|
|
Based on the development plans, the intended architecture is:
|
||
|
|
|
||
|
|
### Stack (From plan-for-devs.md:6-13)
|
||
|
|
- **Monorepo**: pnpm workspaces
|
||
|
|
- **Language**: TypeScript everywhere (Next.js + tRPC or Nest.js API / BullMQ worker)
|
||
|
|
- **Database**: PostgreSQL 15 via Prisma
|
||
|
|
- **Queues**: Redis + BullMQ for background jobs
|
||
|
|
- **Containers**: Docker dev-container with Docker Compose
|
||
|
|
|
||
|
|
### Core Components
|
||
|
|
- **Frontend**: Next.js with drag-and-drop upload, progress tracking, review table
|
||
|
|
- **Backend API**: Authentication (Google OAuth), quota management, batch processing
|
||
|
|
- **Worker Service**: Image processing, virus scanning (ClamAV), AI vision analysis
|
||
|
|
- **Object Storage**: MinIO (S3-compatible) for image storage
|
||
|
|
|
||
|
|
### Database Schema (From plan-for-devs.md:39-42)
|
||
|
|
- `users` table with Google OAuth integration
|
||
|
|
- `batches` table for upload sessions
|
||
|
|
- `images` table for individual image processing
|
||
|
|
|
||
|
|
## Key Features & Requirements
|
||
|
|
|
||
|
|
### Quota System
|
||
|
|
- **Basic Plan**: 50 images/month (free)
|
||
|
|
- **Pro Plan**: 500 images/month
|
||
|
|
- **Max Plan**: 1,000 images/month
|
||
|
|
|
||
|
|
### Processing Pipeline
|
||
|
|
1. File upload with SHA-256 deduplication
|
||
|
|
2. Virus scanning with ClamAV
|
||
|
|
3. Google Cloud Vision API for image labeling (>0.40 confidence)
|
||
|
|
4. Filename generation algorithm
|
||
|
|
5. Real-time progress via WebSockets
|
||
|
|
6. Review table with inline editing
|
||
|
|
7. ZIP download with preserved EXIF data
|
||
|
|
|
||
|
|
## Development Workflow
|
||
|
|
|
||
|
|
### Branch Strategy (From plan-for-devs.md:18-26)
|
||
|
|
- **Main branch**: `main` (always deployable)
|
||
|
|
- **Feature branches**: `feature/*`, `bugfix/*`
|
||
|
|
- **Release branches**: `release/*` (optional)
|
||
|
|
- **Hotfix branches**: `hotfix/*`
|
||
|
|
|
||
|
|
### Team Structure (From plan-for-devs.md:17-25)
|
||
|
|
- **Dev A**: Backend/API (Auth, quota, DB migrations)
|
||
|
|
- **Dev B**: Worker & Vision (Queue, ClamAV, Vision processing)
|
||
|
|
- **Dev C**: Frontend (Dashboard, drag-and-drop, review table)
|
||
|
|
|
||
|
|
## Security & Compliance
|
||
|
|
|
||
|
|
### Requirements
|
||
|
|
- Google OAuth 2.0 with email scope only
|
||
|
|
- GPG/SSH signed commits required
|
||
|
|
- Branch protection on `main` with 2 reviewer approvals
|
||
|
|
- ClamAV virus scanning before processing
|
||
|
|
- Rate limiting on all API endpoints
|
||
|
|
- Secrets stored in Forgejo encrypted vault
|
||
|
|
|
||
|
|
### Data Handling
|
||
|
|
- Only hashed emails stored
|
||
|
|
- EXIF data preservation
|
||
|
|
- Secure object storage paths: `/{batchUuid}/{filename}`
|
||
|
|
|
||
|
|
## Development Environment
|
||
|
|
|
||
|
|
### Local Setup (From plan-for-devs.md:32-37)
|
||
|
|
```yaml
|
||
|
|
# docker-compose.dev.yml services needed:
|
||
|
|
- postgres
|
||
|
|
- redis
|
||
|
|
- maildev (for testing)
|
||
|
|
- minio (S3-compatible object store)
|
||
|
|
- clamav
|
||
|
|
```
|
||
|
|
|
||
|
|
### CI/CD Pipeline (From plan-for-devs.md:46-52)
|
||
|
|
- ESLint + Prettier + Vitest/Jest + Cypress
|
||
|
|
- Forgejo Actions with Docker runner
|
||
|
|
- Multi-stage Dockerfile (≤300MB final image)
|
||
|
|
- Status checks required for merge
|
||
|
|
|
||
|
|
## API Endpoints
|
||
|
|
|
||
|
|
### Core Endpoints (From plan-for-devs.md:49-52)
|
||
|
|
- `/api/batch` - Create new batch, accept multipart form
|
||
|
|
- `/api/batch/{id}/status` - Get processing status
|
||
|
|
- `/api/batch/{id}/zip` - Download renamed images
|
||
|
|
- WebSocket connection for real-time progress updates
|
||
|
|
|
||
|
|
## Performance & Monitoring
|
||
|
|
|
||
|
|
### Targets
|
||
|
|
- Lighthouse scores ≥90
|
||
|
|
- OpenTelemetry trace IDs
|
||
|
|
- Prometheus histograms
|
||
|
|
- Kubernetes liveness & readiness probes
|
||
|
|
|
||
|
|
## Important Files
|
||
|
|
|
||
|
|
- `README.md` - Full product specification
|
||
|
|
- `plan-for-devs.md` - Development workflow and team structure
|
||
|
|
- `plan.md` - Detailed 7-week development backlog
|
||
|
|
|
||
|
|
## No Build Commands Available
|
||
|
|
|
||
|
|
This repository currently contains only planning documents. No package.json, requirements.txt, or other dependency files exist yet. The actual codebase implementation will follow the technical specifications outlined in the planning documents.
|