CLAUDE.md

1# GenSlides Backend - Development Guidelines
2 
3IMPORTANT: always use latest dependencies.
4 
5## Tech Stack
6 
7- **Language**: Python 3.11+
8- **Framework**: FastAPI
9- **Package Manager**: uv
10- **Image Generation**: Google AI SDK (Gemini)
11- **Data Storage**: File system (YAML + images)
12 
13## Architecture Principles
14 
15### SOLID Principles
16 
17- **S - Single Responsibility**: Each module has one clear purpose
18  - `api/routes/` - HTTP request handling only
19  - `services/` - Business logic only
20  - `repositories/` - Data persistence only
21  - `clients/` - External API communication only
22 
23- **O - Open/Closed**: Use abstractions for extensibility
24  - Define protocols/interfaces for services
25  - New image generators can be added without modifying existing code
26 
27- **L - Liskov Substitution**: Subtypes must be substitutable
28  - All repository implementations must honor the same contract
29 
30- **I - Interface Segregation**: Small, focused interfaces
31  - Separate schemas for request/response
32  - Don't force clients to depend on methods they don't use
33 
34- **D - Dependency Inversion**: Depend on abstractions
35  - Services receive repositories via dependency injection
36  - Use FastAPI's `Depends()` for DI
37 
38### YAGNI (You Aren't Gonna Need It)
39 
40- Don't add features until they're actually needed
41- No premature abstractions
42- Start simple, refactor when patterns emerge
43 
44### KISS (Keep It Simple, Stupid)
45 
46- Prefer straightforward solutions over clever ones
47- Minimize layers of indirection
48- Use standard library when possible
49 
50### DRY (Don't Repeat Yourself)
51 
52- Avoid duplicating code
53- Use functions, classes, and modules to DRY code
54- Use patterns and templates to DRY code
55 
56## Code Organization
57 
58```
59backend/
60├── main.py              # FastAPI app entry, router registration
61├── config.py            # Settings via pydantic-settings
62├── api/                 # HTTP layer
63│   ├── routes/          # Route handlers (thin, delegate to services)
64│   ├── schemas/         # Pydantic models for request/response
65│   └── dependencies.py  # FastAPI dependencies (DI setup)
66├── services/            # Business logic layer
67├── repositories/        # Data access layer
68├── models/              # Domain models (dataclasses)
69├── clients/             # External service clients
70└── utils/               # Pure utility functions
71```
72 
73### Layer Responsibilities
74 
75| Layer        | Responsibility                | Can Call              |
76|--------------|-------------------------------|-----------------------|
77| Routes       | HTTP handling, validation     | Services              |
78| Services     | Business logic, orchestration | Repositories, Clients |
79| Repositories | Data persistence              | File system           |
80| Clients      | External APIs                 | External services     |
81 
82### Import Rules
83 
84```python
85# ALLOWED
86from services.slide_service import SlideService  # routes -> services
87from repositories.slide_repository import SlideRepository  # services -> repositories
88from clients.gemini_client import GeminiClient  # services -> clients
89 
90# NOT ALLOWED
91from api.routes.slides import router  # services should not import routes
92from services.slide_service import SlideService  # repositories should not import services
93```
94 
95## Concurrency
96 
97### Async/Await Best Practices
98 
99```python
100# Use async for I/O-bound operations
101async def generate_image(self, prompt: str) -> bytes:
102    # Gemini API call is I/O-bound
103    response = await self.client.models.generate_content_async(...)
104    return response
105 
106# Use sync for CPU-bound operations
107def compute_hash(content: str) -> str:
108    # Blake3 hashing is CPU-bound, keep sync
109    return blake3.blake3(content.encode()).hexdigest()[:16]
110```
111 
112### File I/O
113 
114```python
115# For file operations, use aiofiles or run_in_executor
116import aiofiles
117 
118async def save_image(self, path: Path, data: bytes) -> None:
119    async with aiofiles.open(path, 'wb') as f:
120        await f.write(data)
121 
122# Or use run_in_executor for sync file ops
123from functools import partial
124import asyncio
125 
126async def read_yaml(self, path: Path) -> dict:
127    loop = asyncio.get_event_loop()
128    return await loop.run_in_executor(None, partial(yaml.safe_load, path.read_text()))
129```
130 
131### Parallel Image Generation
132 
133```python
134# Generate multiple images concurrently
135async def generate_style_candidates(self, prompt: str) -> list[bytes]:
136    tasks = [
137        self._generate_single(f"{prompt} (variant {i})")
138        for i in range(2)
139    ]
140    return await asyncio.gather(*tasks)
141```
142 
143## Error Handling
144 
145### Exception Hierarchy
146 
147```python
148# models/exceptions.py
149class GenSlidesError(Exception):
150    """Base exception for all application errors"""
151    pass
152 
153class ProjectNotFoundError(GenSlidesError):
154    """Raised when project/slug doesn't exist"""
155    pass
156 
157class SlideNotFoundError(GenSlidesError):
158    """Raised when slide doesn't exist"""
159    pass
160 
161class ImageGenerationError(GenSlidesError):
162    """Raised when Gemini API fails"""
163    pass
164 
165class ValidationError(GenSlidesError):
166    """Raised for invalid input data"""
167    pass
168```
169 
170### HTTP Error Mapping
171 
172```python
173# api/dependencies.py
174from fastapi import HTTPException, status
175 
176def handle_service_error(func):
177    @wraps(func)
178    async def wrapper(*args, **kwargs):
179        try:
180            return await func(*args, **kwargs)
181        except ProjectNotFoundError as e:
182            raise HTTPException(status_code=404, detail=str(e))
183        except SlideNotFoundError as e:
184            raise HTTPException(status_code=404, detail=str(e))
185        except ImageGenerationError as e:
186            raise HTTPException(status_code=502, detail=str(e))
187        except ValidationError as e:
188            raise HTTPException(status_code=422, detail=str(e))
189    return wrapper
190```
191 
192### Error Response Format
193 
194```python
195# Consistent error responses
196{
197    "detail": "Human-readable error message",
198    "error_code": "PROJECT_NOT_FOUND",  # Optional: machine-readable code
199    "context": {}  # Optional: additional context
200}
201```
202 
203## Logging
204 
205### Configuration
206 
207```python
208# config.py
209import logging
210import sys
211 
212def setup_logging(level: str = "INFO") -> None:
213    logging.basicConfig(
214        level=level,
215        format="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
216        datefmt="%Y-%m-%d %H:%M:%S",
217        handlers=[logging.StreamHandler(sys.stdout)]
218    )
219```
220 
221### Usage Patterns
222 
223```python
224import logging
225 
226logger = logging.getLogger(__name__)
227 
228class SlideService:
229    async def create_slide(self, slug: str, content: str) -> Slide:
230        logger.info("Creating slide", extra={"slug": slug, "content_length": len(content)})
231        try:
232            slide = await self._do_create(slug, content)
233            logger.info("Slide created", extra={"slug": slug, "sid": slide.sid})
234            return slide
235        except Exception as e:
236            logger.exception("Failed to create slide", extra={"slug": slug})
237            raise
238```
239 
240### Log Levels
241 
242| Level    | Usage                                                |
243|----------|------------------------------------------------------|
244| DEBUG    | Detailed diagnostic info (disabled in prod)          |
245| INFO     | Normal operations (request received, task completed) |
246| WARNING  | Unexpected but recoverable situations                |
247| ERROR    | Failures that need attention                         |
248| CRITICAL | System-wide failures                                 |
249 
250## Testing
251 
252### Test Structure
253 
254```
255tests/
256├── conftest.py          # Shared fixtures
257├── unit/                # Unit tests (no I/O)
258│   ├── test_services.py
259│   └── test_utils.py
260├── integration/         # Integration tests (with I/O)
261│   ├── test_repositories.py
262│   └── test_api.py
263└── e2e/                 # End-to-end tests
264    └── test_workflows.py
265```
266 
267### Running Tests
268 
269```bash
270# Run all tests
271uv run pytest
272 
273# Run with coverage
274uv run pytest --cov=. --cov-report=html
275 
276# Run specific test file
277uv run pytest tests/unit/test_services.py -v
278```
279 
280## Code Style
281 
282### Formatting & Linting
283 
284```bash
285# Format code
286uv run ruff format .
287 
288# Lint code
289uv run ruff check .
290 
291# Lint and fix
292uv run ruff check --fix .
293```
294 
295### Type Hints
296 
297Always use type hints:
298 
299```python
300from typing import Optional
301from pathlib import Path
302 
303async def get_slide(self, slug: str, sid: str) -> Optional[Slide]:
304    ...
305 
306def compute_hash(content: str) -> str:
307    ...
308```
309 
310### Docstrings
311 
312Use Google-style docstrings for public APIs:
313 
314```python
315def generate_image(self, prompt: str, style_image: Optional[bytes] = None) -> bytes:
316    """Generate an image using Gemini API.
317 
318    Args:
319        prompt: Text description for image generation.
320        style_image: Optional reference image for style consistency.
321 
322    Returns:
323        Generated image as PNG bytes.
324 
325    Raises:
326        ImageGenerationError: If Gemini API fails.
327    """
328```
329 
330## FastAPI Best Practices
331 
332### Router Organization
333 
334```python
335# api/routes/slides.py
336from fastapi import APIRouter, Depends, status
337 
338router = APIRouter(prefix="/api/slides", tags=["slides"])
339 
340@router.get("/{slug}")
341async def get_project(slug: str, service: SlideService = Depends(get_slide_service)):
342    ...
343 
344@router.post("/{slug}", status_code=status.HTTP_201_CREATED)
345async def create_slide(slug: str, request: CreateSlideRequest, ...):
346    ...
347```
348 
349### Dependency Injection
350 
351```python
352# api/dependencies.py
353from functools import lru_cache
354 
355@lru_cache
356def get_settings() -> Settings:
357    return Settings()
358 
359def get_slide_repository(settings: Settings = Depends(get_settings)) -> SlideRepository:
360    return SlideRepository(settings.slides_base_path)
361 
362def get_slide_service(
363    slide_repo: SlideRepository = Depends(get_slide_repository),
364    image_repo: ImageRepository = Depends(get_image_repository),
365) -> SlideService:
366    return SlideService(slide_repo, image_repo)
367```
368 
369### Response Models
370 
371```python
372# Always specify response_model for documentation
373@router.get("/{slug}", response_model=ProjectResponse)
374async def get_project(slug: str, ...):
375    ...
376 
377# Use status codes explicitly
378@router.delete("/{slug}/{sid}", status_code=status.HTTP_204_NO_CONTENT)
379async def delete_slide(slug: str, sid: str, ...):
380    ...
381```
382