Filamenteka/CLAUDE.md

CLAUDE.md

This file provides guidance for AI-assisted development 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

# 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

# Security & Quality
npm run security:check  # Check for credential leaks
npm run test:build      # Test if build succeeds

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

# Pre-commit Hook
./scripts/pre-commit.sh # Runs security, build, and test checks

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

API Structure

• /api - Node.js Express server (runs on EC2)
  • /server.js - Main server file
  • /routes - API endpoints for filaments, colors, auth
  • Database: PostgreSQL on AWS RDS

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

Data Models

Filament Schema (PostgreSQL)

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

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)
}

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')

API Server (EC2)

• Manual deployment via scripts/deploy-api.sh
• Server: 3.71.161.51
• Domain: api.filamenteka.rs

Database (RDS PostgreSQL)

• Host: filamenteka.ci7fsdlbzmag.eu-central-1.rds.amazonaws.com
• Migrations in /database/migrations/
• Schema in /database/schema.sql

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
• Coverage goal: >80%

Environment Variables

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

# API Server
DATABASE_URL=postgresql://...
JWT_SECRET=...
NODE_ENV=production

Security Considerations

• Admin routes protected by JWT authentication
• Password hashing with bcrypt
• SQL injection prevention via parameterized queries
• Credential leak detection in pre-commit hooks
• CORS configured for production domains only

Database Operations

When modifying the database:

1. Create migration file in /database/migrations/
2. Test locally first
3. Run migration on production via scripts
4. Update corresponding TypeScript types

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