# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Structure

Studio-m is a monorepo using Turbo for build orchestration. It consists of:

### Apps
- **`apps/api`**: NestJS backend API with Fastify adapter
- **`apps/front`**: Vue 3 + Ionic mobile-first web application

### Packages
- **`packages/common`**: Shared Vue components, utilities, and API client
- **`packages/app-types`**: Shared TypeScript type definitions
- **`packages/date-helper`**: Date manipulation utilities  
- **`packages/functions`**: Shared business logic functions
- **`packages/tools`**: General utility functions

## Development Commands

**Start development environment:**
```bash
npm run dev  # Starts both frontend and API in watch mode
```

**Individual app development:**
```bash
# Frontend only
cd apps/front && npm run dev

# API only  
npm run start-api
# or
cd apps/api && npm run dev
```

**Building:**
```bash
npm run build              # Build all apps
npm run build-front        # Frontend production build only
npm run build-packages     # Build shared packages only
```

**Testing:**
```bash
# API tests
cd apps/api && npm run test
cd apps/api && npm run test:watch
cd apps/api && npm run test:e2e

# Frontend tests  
cd apps/front && npm run test:unit
cd apps/front && npm run test:e2e
```

**Database:**
```bash
npm run migrate-api        # Push Prisma schema to database
# or
cd apps/api && npx prisma db push
```

**Linting:**
```bash
cd apps/api && npm run lint
cd apps/front && npm run lint
```

## Architecture Overview

### Backend (NestJS + Fastify + Prisma)
- **Framework**: NestJS with Fastify adapter for performance
- **Database**: MySQL with Prisma ORM
- **Authentication**: JWT-based auth with role-based access (USER, ADMIN, SUPER_ADMIN)
- **File handling**: Fastify static files + multer for uploads
- **Core structure**:
  - `src/models/`: Domain models (users, shootings, customers)
  - `src/modules/`: Technical modules (multer, health)
  - `src/core/`: Domain-driven design primitives (UseCase, DomainEvent)
  - `src/database/`: Prisma integration and helpers
  - `src/filters/`: Global exception handling

### Frontend (Vue 3 + Ionic + Capacitor)
- **Framework**: Vue 3 with Composition API + Ionic UI components
- **Mobile**: Capacitor for native mobile capabilities
- **Styling**: TailwindCSS + Ionic CSS variables
- **State**: TanStack Vue Query for server state
- **PWA**: Vite PWA plugin with custom service worker
- **Key features**:
  - `src/views/`: Page components and routing
  - `src/components/`: Reusable UI components
  - `src/plugins/`: Vue plugin configurations
  - `src/theme/`: Design system and styling

### Shared Packages Architecture
- **Type safety**: Centralized TypeScript types in `@studio-m/app-types`
- **Component library**: Shared Vue components in `@studio-m/common`
- **Domain logic**: Business rules and validation in `@studio-m/functions`
- **Utilities**: Pure functions and helpers in `@studio-m/tools`

## Key Patterns

### API Patterns
- **Module-based architecture**: Each domain has its own module (users, shootings, customers)
- **Domain-driven design**: UseCase classes for business logic, DomainEvents for side effects
- **Guard-protected routes**: Global AuthGuard with role-based permissions
- **Prisma extensions**: Uses soft-delete extension for logical deletion

### Frontend Patterns  
- **Ionic + Vue Router**: Page-based routing with Ionic transitions
- **Component composition**: Uses Vue 3 Composition API throughout
- **Shared module system**: Domain-specific modules in `packages/common/src/modules/`
- **TanStack Query**: Server state management with caching and optimistic updates

### Monorepo Patterns
- **Workspace dependencies**: Internal packages referenced by workspace name (e.g., `@studio-m/common`)
- **Turbo orchestration**: Parallel builds and cache optimization
- **Shared tooling**: ESLint, TypeScript, and build configs shared across packages

## Deployment

**Production build and deploy:**
```bash
npm run deploy  # Builds frontend and runs deploy.js
```

The deploy script builds the frontend and uploads to the configured server using environment variables from `.env.deploy`.

## Development Notes

- **Database URL**: Set in `apps/api/.env` for local development
- **File uploads**: Configured via `UPLOAD_PATH` environment variable
- **CORS**: Currently set to accept all origins in development
- **Module imports**: Always use workspace names (e.g., `@studio-m/common`) rather than relative paths
- **TypeScript**: Strict mode enabled across all packages
- **Mobile testing**: Use `npm run dev` then access via IP for mobile device testing