Filamenteka/CLAUDE.md

# CLAUDE.md

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

## Project Overview

Filamenteka is a 3D printing filament inventory management system for tracking Bambu Lab filaments. It consists of:
- **Frontend**: Next.js app with React, TypeScript, and Tailwind CSS (static export)
- **Backend**: Node.js API server with PostgreSQL database
- **Infrastructure**: AWS (Amplify for frontend, EC2 for API, RDS for database)

## Critical Rules

- NEVER mention ANY author in commits. No author tags or attribution
- NEVER mention AI/assistant names anywhere
- Keep commit messages clean and professional with NO attribution
- Build for AMD64 Linux when deploying (development is on ARM macOS)
- Always run security checks before commits

## Common Commands

```bash
# Development
npm run dev              # Start Next.js development server (port 3000)
npm run build            # Build static export to /out directory
npm run lint             # Run ESLint
npm test                 # Run Jest tests
npm run test:watch       # Run Jest in watch mode

# Security & Quality
npm run security:check   # Check for credential leaks
npm run test:build       # Test if build succeeds
./scripts/pre-commit.sh  # Runs security, build, and test checks (use before commits)

# Database Migrations
npm run migrate          # Run pending migrations
npm run migrate:clear    # Clear migration history
```

## Architecture

### Frontend Structure (Next.js App Router)
- `/app` - Next.js 13+ app directory structure
  - `/page.tsx` - Public filament inventory table
  - `/upadaj` - Admin panel (password protected)
    - `/page.tsx` - Admin login
    - `/dashboard/page.tsx` - Filament CRUD operations
    - `/colors/page.tsx` - Color management
    - `/requests/page.tsx` - Customer color requests
- `/src` - Source files
  - `/components` - React components
  - `/services/api.ts` - Axios instance with auth interceptors
  - `/data` - Color definitions (bambuLabColors.ts, bambuLabColorsComplete.ts)
  - `/types` - TypeScript type definitions

### API Structure
- `/api` - Node.js Express server (runs on EC2, port 80)
  - `/server.js` - Main Express server with all routes inline
  - Database: PostgreSQL on AWS RDS
  - Endpoints: `/api/login`, `/api/filaments`, `/api/colors`, `/api/sale/bulk`, `/api/color-requests`

### Key Components
- `FilamentTableV2` - Main inventory display with sorting/filtering
- `SaleManager` - Bulk sale management interface
- `ColorCell` - Smart color rendering with gradient support
- `EnhancedFilters` - Advanced filtering system
- `ColorRequestForm` - Customer color request form
- `ColorRequestModal` - Modal for color requests

### Data Models

#### Filament Schema (PostgreSQL)
```sql
filaments: {
  id: UUID,
  tip: VARCHAR(50),        # Material type (PLA, PETG, ABS)
  finish: VARCHAR(50),     # Finish type (Basic, Matte, Silk)
  boja: VARCHAR(100),      # Color name
  refill: INTEGER,         # Refill spool count
  spulna: INTEGER,         # Regular spool count
  kolicina: INTEGER,       # Total quantity (refill + spulna)
  cena: VARCHAR(50),       # Price
  sale_active: BOOLEAN,    # Sale status
  sale_percentage: INTEGER,# Sale discount
  sale_end_date: TIMESTAMP # Sale expiry
}
```

#### Color Schema
```sql
colors: {
  id: UUID,
  name: VARCHAR(100),      # Color name (must match filament.boja)
  hex: VARCHAR(7),         # Hex color code
  cena_refill: INTEGER,    # Refill price (default: 3499)
  cena_spulna: INTEGER     # Regular price (default: 3999)
}
```

#### Color Requests Schema
```sql
color_requests: {
  id: UUID,
  color_name: VARCHAR(255), # Requested color name
  message: TEXT,            # Customer message
  contact_name: VARCHAR(255), # Customer name (required)
  contact_phone: VARCHAR(50), # Customer phone (required)
  status: VARCHAR(20),      # Status: pending, reviewed, fulfilled
  created_at: TIMESTAMP
}
```

## Deployment

### Frontend (AWS Amplify)
- Automatic deployment on push to main branch
- Build output: Static files in `/out` directory
- Config: `amplify.yml`, `next.config.js` (output: 'export')
- Security check runs during build (amplify.yml preBuild phase)

### API Server (EC2)
- Manual deployment via `scripts/deploy-api.sh` or `scripts/deploy-api-update.sh`
- Server: `3.71.161.51`
- Domain: `api.filamenteka.rs`
- Service: `node-api` (systemd)
- IMPORTANT: When deploying API, remember to build for AMD64 Linux (not ARM macOS)

### Database (RDS PostgreSQL)
- Host: `filamenteka.ci7fsdlbzmag.eu-central-1.rds.amazonaws.com`
- User: `filamenteka_admin`
- Database: `filamenteka`
- Migrations in `/database/migrations/`
- Schema in `/database/schema.sql`
- Use `scripts/update-db-via-aws.sh` for running migrations on production

## Important Patterns

### API Communication
- All API calls use axios interceptors for auth (`src/services/api.ts`)
- Auth token stored in localStorage
- Automatic redirect on 401/403 in admin routes

### Color Management
- Colors defined in `src/data/bambuLabColors.ts` and `bambuLabColorsComplete.ts`
- Automatic row coloring based on filament color
- Special handling for gradient filaments

### State Management
- React hooks for local state
- No global state management library
- Data fetching in components with useEffect

### Testing
- Jest + React Testing Library
- Tests in `__tests__/` directory
- Config: `jest.config.js`, `jest.setup.js`
- Coverage goal: >80%
- Run with `npm test` or `npm run test:watch`
- Tests include: component tests, API integration tests, data consistency checks

## Environment Variables

```bash
# Frontend (.env.local)
NEXT_PUBLIC_API_URL=https://api.filamenteka.rs/api

# API Server (.env in /api directory)
DATABASE_URL=postgresql://filamenteka_admin:PASSWORD@filamenteka.ci7fsdlbzmag.eu-central-1.rds.amazonaws.com:5432/filamenteka
JWT_SECRET=...
ADMIN_PASSWORD=...
NODE_ENV=production
PORT=80
```

## Security Considerations

- Admin routes protected by JWT authentication (24h expiry)
- Password hashing with bcrypt (for future multi-user support)
- SQL injection prevention via parameterized queries
- Credential leak detection in pre-commit hooks (`scripts/security/security-check.js`)
- CORS configured to allow all origins (update for production hardening)
- Auth token interceptors handle 401/403 automatically
- Pre-commit hook runs security checks, build tests, and unit tests

## Database Operations

When modifying the database:
1. Create migration file in `/database/migrations/` with sequential numbering
2. Test locally first
3. Run migration on production:
   - Use `scripts/update-db-via-aws.sh` for remote execution
   - Or use `npm run migrate` for local/scripted execution
4. Update corresponding TypeScript types in `/src/types/`

Important database constraints:
- `filaments.boja` has foreign key to `colors.name` (ON UPDATE CASCADE)
- `filaments.kolicina` has check constraint: `kolicina = refill + spulna`
- Always update `colors` table first before adding filaments with new colors

## Terraform Infrastructure

Infrastructure as Code in `/terraform/`:
- VPC and networking setup
- EC2 instance for API
- RDS PostgreSQL database
- Application Load Balancer
- ECR for Docker images
- Cloudflare DNS integration