# CLAUDE.md

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

## Project Overview

This is a multi-platform manufacturing and CAD system called "FikoYT" with the following major components:

1. **fikoyt-zorro.com** - Angular 20 web application with advanced 3D CAD viewer
2. **docker/fikoyt-sunucu** - Go/Fiber backend server with Socket.IO support
3. **flutter/** - Multiple Flutter mobile/desktop applications
4. **Python/** - FreeCAD API server for CAD file processing
5. **src/service/fikoyt-ui** - Shared UI library with Three.js-based 3D engine

## Architecture

### Frontend (fikoyt-zorro.com)
- Angular 20 with Ng-Zorro UI components
- Custom Three.js-based CAD engine with WebGL2/GPU acceleration
- WASM modules for high-performance CAD operations (Rust)
- WebWorkers for parallel processing (geometry, STP parsing, surface detection)
- Occt-import-js for STEP file parsing

### Backend (docker/fikoyt-sunucu/merkez.go-server.com)
- Go 1.23+ with Fiber v3 framework
- MongoDB for data persistence
- Socket.IO for real-time communication
- FreeCAD Python API server for CAD file conversion
- SSL/TLS with prefork enabled

### 3D Engine Architecture (fikoyt-ui)
The custom 3D CAD engine is located in `src/service/fikoyt-ui/src/lib/fiko-three-js/IFikoThreeJS/`:

**Core Selection System:**
- `FikoSecililer.ts` - Main selection manager with multi-tier architecture:
  1. WASM batch processing (10-50x faster) via `FikoWasmBridge.ts`
  2. GPU-accelerated selection via `FikoGPUSelection.ts`
  3. CPU fallback with BVH optimization via `FikoRaycastBVH.ts`

**Performance-Critical Components:**
- `FikoImporter.STP.ts` - STEP file importer with WASM acceleration
- `FikoGPUPicker.ts` - GPU-based object picking
- `FikoInstancedEdgeRenderer.ts` - Optimized edge rendering
- `FikoWasmBridge.ts` - Bridge to Rust WASM modules

**CAD Features:**
- `FikoCizimYalin.ts` - CAD drawing tools
- `FikoOlcumCizgisi.ts` - Measurement tools
- `fiko-olcum/` - Measurement subsystem

**Optimization Layers:**
- GPU compute pipeline (`FikoGPU*.ts` files)
- LOD system (`FikoAdvancedLOD.ts`, `FikoAggressiveLOD.ts`)
- Occlusion culling (`FikoOcclusionCulling.ts`)
- Worker pools (`FikoWorkerPool.ts`, `FikoComputeWorkerPool.ts`)

## Development Commands

### Angular Frontend (fikoyt-zorro.com)

```bash
# Development server with SSL (runs on https://0.0.0.0:444)
cd fikoyt-zorro.com
npm install
npm start
# Or: ng serve

# Production build
npm run build
# Or: ng build

# Run tests
npm test
# Or: ng test
```

### WASM Module Build (fikoyt-zorro.com/fikoyt-wasm)

**Prerequisites:** Install Rust, wasm-bindgen-cli, and optionally binaryen (wasm-opt)

```bash
# Install Rust (Windows - as Administrator)
.\rustup-init.exe -y

# Add WASM target
rustup target add wasm32-unknown-unknown

# Install wasm-bindgen-cli (replaces wasm-pack)
cargo install wasm-bindgen-cli

# Optional: Install binaryen for wasm-opt (smaller binaries)
# cargo install wasm-opt  OR  download from https://github.com/WebAssembly/binaryen/releases

# Build WASM module (development)
cd fikoyt-zorro.com/fikoyt-wasm
bash build.sh

# Build WASM module (production - aggressive optimization)
bash build-production-wasm.sh

# Manual build steps (if not using build.sh):
cargo build --target wasm32-unknown-unknown --release
wasm-bindgen target/wasm32-unknown-unknown/release/fikoyt_wasm.wasm --out-dir pkg --target web --typescript
wasm-opt pkg/fikoyt_wasm_bg.wasm -o pkg/fikoyt_wasm_bg.wasm -Os --enable-simd --enable-bulk-memory

# Verify output (~120-150 KB WASM file, not 8 bytes placeholder)
ls ../public/assets/fikoyt-wasm/fikoyt_wasm*
```

**Build Pipeline:** `cargo build` → `wasm-bindgen` → `wasm-opt` → copy to `public/assets/fikoyt-wasm/`

**Expected WASM outputs:**
- `fikoyt_wasm_bg.wasm` - Main WASM binary (~120-150 KB)
- `fikoyt_wasm_bg.js` - JS glue code
- `fikoyt_wasm.js` - Module exports
- `fikoyt_wasm.d.ts` - TypeScript definitions

### Go Backend (docker/fikoyt-sunucu/merkez.go-server.com)

```bash
cd docker/fikoyt-sunucu/merkez.go-server.com

# Install dependencies
go mod download

# Build
go build -o server .

# Run (requires MongoDB and SSL certificates)
./server

# Build for production
go build -ldflags="-s -w" -o server .
```

**Environment:** Requires `fikoyt.env.json` configuration file

### Flutter Applications

```bash
cd flutter/[app-name]  # e.g., fikoyt_mesaici, fikoyt_akcali, fikoyt_sistem

# Get dependencies
flutter pub get

# Run on connected device
flutter run

# Build for Windows
flutter build windows

# Build for Android
flutter build apk
```

**Available Flutter apps:**
- `fikoyt_mesaici` - Worker/operator interface
- `fikoyt_akcali` - Smart factory interface
- `fikoyt_sistem` - System management
- `fikoyt_hmi_pano` - HMI panel
- `fikoyt_ui` - Shared UI library

### Python/FreeCAD Server

```bash
cd Python

# Run FreeCAD API server
freecad freecad_api_server.py

# Or with Python directly
python freecad_api_server.py
```

### Docker Services

```bash
# Start all services
cd docker
docker-compose up -d

# Individual services
cd docker/mongo-db && docker-compose up -d
cd docker/fikoyt-sunucu && docker-compose up -d
cd docker/n8n && docker-compose up -d
```

**Available services:** MongoDB, n8n automation, Ollama AI, Rocket.Chat, SearXNG, ntfy notifications

## TypeScript Configuration

The project uses relaxed TypeScript settings for rapid development:
- `strict: false`
- `strictNullChecks: false`
- No implicit return/override checks

When making changes, prioritize functionality over strict typing. The codebase has ~40 TypeScript hints (mostly unused variables) which are acceptable.

## Performance Optimization Guidelines

### 3D Engine Performance
**CRITICAL:** The 3D selection system has been heavily optimized. Recent changes in `PERFORMANS_OPTIMIZASYONU_RAPORU.md`:

1. **Zero-allocation inner loops** - Reuse Vector3 buffers, no object creation in hot paths
2. **WASM batch processing** - Use `tryWasmEdgeDistance()` for edge operations (10-50x faster)
3. **GPU fallback** - `FikoGPUSelection` with WebGL2 compute
4. **BVH acceleration** - Use `three-mesh-bvh` for raycasting
5. **Occlusion caching** - 500ms TTL on mesh object cache

**When modifying selection/picking code:**
- Never allocate in loops (use pre-allocated buffers)
- Always try WASM → GPU → CPU in that order
- Wrap WASM calls in try-catch (graceful degradation)
- Use inline matrix operations (no Vector3/Vector4 allocation)

### WASM Integration
The WASM bridge (`FikoWasmBridge.ts`) provides:
- `parseStepTopology()` - STEP file parsing
- `detectEdgesFromMesh()` - Edge detection
- Batch edge distance calculations

**Always check WASM availability before use:**
```typescript
if (this.wasmModule?.detectEdgesFromMesh) {
  // Use WASM
} else {
  // CPU fallback
}
```

## Key File Locations

### Configuration Files
- `fikoyt-zorro.com/angular.json` - Angular build config, SSL paths
- `fikoyt-zorro.com/tsconfig.json` - TypeScript settings
- `docker/fikoyt-sunucu/merkez.go-server.com/fikoyt.env.json` - Backend config
- `docker/fikoyt-sunucu/merkez.go-server.com/go.mod` - Go dependencies

### Critical 3D Engine Files
- `src/service/fikoyt-ui/src/lib/fiko-three-js/IFikoThreeJS/FikoSecililer.ts:3037-3655` - Optimized selection pipeline
- `src/service/fikoyt-ui/src/lib/fiko-three-js/IFikoThreeJS/FikoGPUSelection.ts:504-632` - GPU selection fallback
- `src/service/fikoyt-ui/src/lib/fiko-three-js/IFikoThreeJS/FikoWasmBridge.ts` - WASM interface
- `src/service/fikoyt-ui/src/lib/fiko-three-js/IFikoThreeJS/FikoImporter.STP.ts` - STEP file importer

### Backend API Structure
- `docker/fikoyt-sunucu/merkez.go-server.com/main.go` - Server entry point
- `docker/fikoyt-sunucu/merkez.go-server.com/apps/uyar_dokum/uyar/` - Main application logic
- `docker/fikoyt-sunucu/merkez.go-server.com/sistem/` - Core system modules

## Build Output & Deployment

### Angular Production Build
```bash
cd fikoyt-zorro.com
ng build --configuration production
# Output: dist/fikoyt-zorro.com/browser/
```

### Go Server Binary
```bash
cd docker/fikoyt-sunucu/merkez.go-server.com
go build -o server .
# Output: server.exe (Windows) or server (Linux)
```

## SSL/TLS Configuration

The Angular dev server runs with SSL on port 444 using certificates from:
```
D:/__sistem__/Masaustu/FikoYT.Yeni.Cag/docker/fikoyt-sunucu/merkez.go-server.com/cert/
- server.crt
- server.key
```

## Common Workflows

### Adding a New 3D Feature
1. Create service in `src/service/fikoyt-ui/src/lib/fiko-three-js/services/`
2. Implement core logic in `IFikoThreeJS/FikoNewFeature.ts`
3. Register in `fiko-three-js.component.ts`
4. Add to appropriate component in `src/app/uygulamalar/`

### Optimizing Performance
1. Profile with `fiko-performance-monitor.component.ts`
2. Check WASM availability for compute-heavy operations
3. Use GPU compute shaders for parallel work
4. Implement LOD for large meshes
5. Use worker pools for background processing

### STEP File Import Flow
1. User uploads file → `FikoImporter.ts`
2. Parsed by `FikoImporter.STP.ts` using occt-import-js
3. Optional WASM acceleration via `FikoWasmBridge.ts`
4. Geometry processed by `stp-processor.worker.ts`
5. Rendered with `FikoInstancedEdgeRenderer.ts` for edges
6. Selection handled by `FikoSecililer.ts` multi-tier system

## Testing

### Frontend Tests
```bash
cd fikoyt-zorro.com
ng test  # Karma + Jasmine
```

### Backend Tests
```bash
cd docker/fikoyt-sunucu/merkez.go-server.com
go test ./...
```

### WASM Tests
```bash
cd fikoyt-zorro.com/fikoyt-wasm
cargo test
```

## Dependencies & Versions

- **Angular:** 20.0.0-rc.0
- **Three.js:** 0.177.0
- **Go:** 1.23.2
- **Flutter:** Latest stable
- **Rust:** Latest stable (for WASM)
- **TypeScript:** 5.8.3

## Performance Targets

- Edge selection: <5ms (with WASM)
- STEP file import: 50-70% faster with WASM vs pure JS
- Frame budget: Maintain 60 FPS in 3D viewport
- Memory: <10 allocations per frame in hot paths

## Kullanıcı Tercihleri (KESİNLİKLE UYULMALI)

### Çalışma Tarzı
- **Küçük işler** → direkt uygula, plan sorma
- **Büyük işler (3+ dosya)** → 2-3 maddelik kısa plan sun
- **Yanıt** → Kısa ve öz. 1-2 cümle, özet tekrarı yapma
- **Commit** → Sadece kullanıcı söylediğinde at, otomatik atma
- **Test** → Sadece kritik iş mantığı için (kesim motoru, geometri hesabı)
- **İsimlendirme** → Türkçe (teknik terimler hariç)
- **Hata mesajları** → Kullanıcıya gösterilen tüm mesajlar Türkçe
- **Loglama** → Debug için console.log kullan, kullanıcı onayladıktan sonra hemen temizle

### KRİTİK: Performans Her Zaman En Üst Öncelik
- `OnPush` + `signal()` + `trackBy` her zaman
- Büyük listeler → virtual scroll
- Ağır hesap → `computed()` veya WebWorker
- Lazy loading → route bazlı `loadComponent`
- CSS animasyonları → `transform`/`opacity` (layout tetikleme)
- Gereksiz re-render, DOM manipülasyonu, büyük import'lardan kaçın
- Go'da gereksiz middleware zinciri ekleme, MongoDB'de index kullan

### KRİTİK: Kod Yazma Kuralları
**HER KOD YAZMADAN ÖNCE:**
1. Mevcut dosyaları/fonksiyonları incele — aynı iş yapılmış mı?
2. Mevcut stilleri kontrol et — global stil tanımlı mı?
3. Varsa onu kullan/genişlet — yoksa yeni yaz
4. Bir fonksiyon birçok yerde kullanılabilir → merkezi utility yap
5. OOP mantığıyla minimal kodla ilerle, dosyaları kodla doldurma

### Kaçınılacaklar
- Gereksiz `//` yorum ekleme
- Fazla dosya oluşturma (mevcut dosyaları düzenle)
- Over-engineering (basit çözüm yeterliyken karmaşık pattern kullanma)
- Özet tekrarı (yaptıklarını sonunda listeleme)
- Dosyaları kodla doldurma (merkezi ve modüler tut)

### Proaktiflik
- Açık dosyada hata/küçük bug → sormadan düzelt
- Performans/güvenlik sorunu → sadece uyar, dokunma
- 3. parti kütüphane → gerekiyorsa serbest ekle
- 3D sahnede sis (fog) kullanma

### UI Tasarım
- Ng-Zorro + Fomantic-UI, merkezi global stil
- Dark + Light tema (toggle ile geçiş, CSS custom properties)
- Bol animasyon (geçiş, hover, micro-interaction)
- Tam responsive (mobil dahil)

### Go Backend
- Mevcut sistem modüllerini kullan: `sistem/kok/`, `sistem/kokDB/`, `sistem/fikoyt_ctx/`
- Yeni sistem modülü oluşturma — yetmezse kullanıcıya sor

## Component Şablonu (FikoYTKokBilesenComponent)

Tüm component'ler `FikoYTKokBilesenComponent`'i extend etmeli:

```typescript
// Dosya: src/service/kok-bilesen/kok-bilesen.component.ts
// Her iki projede de var: fikoyt-sistem ve fikoyt-zorro.com

@Component({ ... })
export class YeniBilesenComponent extends FikoYTKokBilesenComponent {
  constructor() { super(); }
}
```

**Base class sağladıkları:** CD, FikoYT, FikoYTArayuz, router, route, sanitizer, elementRef, ngZone, nzMessage, nzNotification, nzModalServis, bPnt (breakpoint), env, subsList, diller, parametreler

## Mevcut Utility Haritası (YENİ KOD YAZMADAN ÖNCE KONTROL ET)

### Ortak Servisler
| Servis | Dosya | İş |
|--------|-------|-----|
| FikoYTRequestService | `shared/services/fikoyt-request.service.ts` | MongoDB CRUD, aggregate, sayfalı sorgu |
| UnifiedCacheService | `shared/services/unified-cache.service.ts` | SWR cache pattern |
| AvatarService | `servisler/avatar.service.ts` | Avatar, yüz crop, cinsiyet gradyan |
| FikoYTService | `service/kok-bilesen/` | Merkezi uygulama servisi |

### Ortak Utility'ler
| Utility | Dosya | İş |
|---------|-------|-----|
| ListeBase<T> | `shared/utils/liste-base.ts` | Liste sayfaları için abstract base |
| bbox.utils | `shared/utils/bbox.utils.ts` | Yüz bounding box |
| gradient-tokens | `shared/utils/gradient-tokens.ts` | Cinsiyet/durum gradyanları |
| firma-ui.utils | `shared/utils/firma-ui.utils.ts` | Avatar harf/renk |
| regex.utils | `shared/utils/regex.utils.ts` | MongoDB regex güvenliği |

### Ortak Bileşenler
| Bileşen | İş |
|---------|-----|
| UniversalAvatarComponent | Çok modlu avatar (crop/resim/harf) |
| FikoFormDrawerComponent | Form drawer (detay/düzenleme) |
| FikoEmptyStateComponent | Boş durum gösterimi |
| AdminPageHeaderComponent | Admin başlık |
| AdminStatCardComponent | İstatistik kartı |

### Dekoratörler (fikoyt-ui)
| Dekoratör | İş |
|-----------|-----|
| @debounce(ms) | Metod geciktirme |
| @throttle(ms) | Rate limiting |
| @memoize() | Sonuç cache |

### Pipe'lar (fikoyt-ui)
| Pipe | İş |
|------|-----|
| toDosyaBoyutu | Byte → KB/MB/GB |
| sanitize | HTML sanitize |
| yuvarla | Sayı yuvarla |

### Helper'lar (fikoyt-ui)
| Helper | İş |
|--------|-----|
| FikoYTId | MongoDB-style ID üretici |
| durations.ts | Zaman birimi sabitleri |