Filamenteka/CLAUDE.md

CLAUDE.md

This file provides guidance when working with code in this repository.

Project Overview

Filamenteka is a 3D printing filament inventory management system for tracking Bambu Lab filaments with:

• Frontend: Next.js 15 app with React 19, TypeScript 5.2.2, and Tailwind CSS (static export)
• Backend: Node.js Express API server with PostgreSQL database
• Infrastructure: AWS (Amplify for frontend, EC2 for API, RDS for database), managed via Terraform

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
• NEVER use mock data - all tests must use real APIs/data

Common Commands

# 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 (includes no-mock-data validation)

# Security & Quality
npm run security:check  # Check for credential leaks
npm run test:build      # Test if build succeeds
./scripts/pre-commit.sh # Full pre-commit validation (security, build, tests)

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

# API Server Development
cd api && npm start     # Start API server locally (port 3001)
cd api && npm run dev   # Start API server with nodemon

# Deployment
./scripts/deploy-api.sh # Deploy API to EC2 (builds AMD64 Docker image)

Architecture

Frontend Structure (Next.js App Router)

/app
├── page.tsx                    # Public filament inventory table
├── layout.tsx                 # Root layout with providers
└── upadaj/                    # Admin panel (JWT protected)
    ├── page.tsx               # Admin login
    ├── dashboard/page.tsx     # Filament CRUD operations
    ├── colors/page.tsx        # Color management
    └── requests/page.tsx      # Color request management

API Structure

/api
├── server.js                  # Express server (port 3001)
├── routes/
│   ├── filaments.js          # Filament CRUD + bulk operations
│   ├── colors.js             # Color management
│   ├── colorRequests.js      # Color request system
│   └── auth.js               # JWT authentication
└── middleware/
    └── auth.js               # JWT verification middleware

Key Components

• FilamentTableV2 - Main inventory display with sorting/filtering/searching
• SaleManager - Bulk sale management with countdown timers
• ColorCell - Smart color rendering with gradient support
• EnhancedFilters - Multi-criteria filtering system
• ColorRequestModal - Public color request form

Data Models

Filament Schema (PostgreSQL)

filaments: {
  id: UUID PRIMARY KEY,
  tip: VARCHAR(50),        # Material type (PLA, PETG, ABS)
  finish: VARCHAR(50),     # Finish type (Basic, Matte, Silk)
  boja: VARCHAR(100),      # Color name (links to colors.name)
  boja_hex: VARCHAR(7),    # Color hex code
  refill: INTEGER,         # Refill spool count
  spulna: INTEGER,         # Regular spool count
  kolicina: INTEGER,       # Total quantity (refill + spulna)
  cena: VARCHAR(50),       # Price string
  sale_active: BOOLEAN,    # Sale status
  sale_percentage: INTEGER,# Sale discount percentage
  sale_end_date: TIMESTAMP # Sale expiry
}

Color Schema

colors: {
  id: UUID PRIMARY KEY,
  name: VARCHAR(100) UNIQUE,  # 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

color_requests: {
  id: UUID PRIMARY KEY,
  color_name: VARCHAR(100),
  email: VARCHAR(255),
  message: TEXT,
  status: VARCHAR(50),        # pending/approved/rejected
  created_at: TIMESTAMP
}

Deployment

Frontend (AWS Amplify)

• Automatic deployment on push to main branch
• Build output: Static files in /out directory
• Build command: npm run build
• Config: amplify.yml, next.config.js (output: 'export')

API Server (EC2)

• Manual deployment via ./scripts/deploy-api.sh
• Docker containerized (Node.js 18 Alpine)
• Server: 3.71.161.51
• Domain: api.filamenteka.rs
• Important: Build for AMD64 architecture when deploying from ARM Mac

Database (RDS PostgreSQL)

• Host: filamenteka.ci7fsdlbzmag.eu-central-1.rds.amazonaws.com
• Migrations in /database/migrations/ (numbered sequence)
• Schema in /database/schema.sql
• Connection via DATABASE_URL environment variable

Important Patterns

API Communication

• All API calls use axios with interceptors (src/services/api.ts)
• Auth token stored in localStorage as 'adminToken'
• Automatic redirect on 401/403 in admin routes
• Base URL from NEXT_PUBLIC_API_URL env variable

Color Management

• Primary source: src/data/bambuLabColors.ts (hex mappings)
• Extended data: src/data/bambuLabColorsComplete.ts
• Refill-only colors: src/data/refillOnlyColors.ts
• Automatic row coloring based on filament.boja_hex
• Special gradient handling for multi-color filaments

State Management

• React hooks for local state (no global state library)
• Data fetching with useEffect in components
• Form state managed with controlled components
• Admin auth state in localStorage

Testing Strategy

• Jest + React Testing Library for component tests
• Special no-mock-data.test.ts enforces real API usage
• Integration tests connect to real database
• Coverage reports in /coverage/
• Test files in __tests__/ directories

Environment Variables

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

# API Server (.env)
DATABASE_URL=postgresql://username:password@host/database
JWT_SECRET=your-secret-key
NODE_ENV=production
PORT=3001

Security Considerations

• JWT authentication for admin routes (24h expiry)
• Password hashing with bcryptjs (10 rounds)
• SQL injection prevention via parameterized queries
• Credential leak detection in pre-commit hooks
• CORS configured for production domains only
• Author mention detection prevents attribution in commits

Database Operations

When modifying the database:

1. Create numbered migration file in /database/migrations/
2. Test locally with npm run migrate
3. Deploy to production via SSH or migration script
4. Update TypeScript interfaces in src/types/
5. Update relevant data files in src/data/

Terraform Infrastructure

Infrastructure as Code in /terraform/:

• VPC with public/private subnets
• EC2 instance with Application Load Balancer
• RDS PostgreSQL instance
• ECR for Docker image registry
• Cloudflare DNS integration
• Environment separation (dev/prod)

Special Considerations

ARM to AMD64 Builds

When deploying from ARM Mac to AMD64 Linux:

• Docker builds must specify --platform linux/amd64
• Deployment scripts handle architecture conversion
• Test builds locally with docker buildx

Color Data Synchronization

• Colors must exist in both database and frontend data files
• Use migration scripts to sync color data
• Validate consistency with data consistency tests

Sale Management

• Bulk sale operations affect multiple filaments
• Sale countdown timers update in real-time
• Prices automatically calculated with discounts
• Sale end dates trigger automatic deactivation