sam-api/CLAUDE.md

CLAUDE.md

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

Project Architecture

This is a multi-application Laravel-based SAM (Smart Application Management) system consisting of:

Core Applications

• admin/ - Laravel 12 application with Filament admin panel for tenant management
• api/ - Laravel 12 REST API backend with comprehensive API endpoints and Swagger documentation
• front/ - CodeIgniter 3 frontend application
  • front/www/ - Main CodeIgniter application directory
  • front/_Codeigniter/ - CodeIgniter 3 system files (extracted from www)
• 5130/ - Legacy PHP application for construction/manufacturing management
• shared/ - Common models and services package shared between applications
• docker/ - Docker configuration files

Key Features & Components

• Multi-tenant architecture with tenant switching capabilities
• Role-based access control (RBAC) with permissions and departments
• Product management with BOM (Bill of Materials) support
• Material management and inventory tracking
• File upload and management system
• Category management with templates and versioning
• Design workflow with version control and audit logging

Shared Models Structure

The shared/ directory contains common Eloquent models organized by domain:

• Members/ - User and tenant management
• Products/ - Product catalog and BOM structures
• Materials/ - Material specifications and inventory
• Orders/ - Order processing workflows
• Tenants/ - Multi-tenant configurations
• Commons/ - Shared utilities and common data

Development Commands

Admin Application (admin/)

# Development server with all services
composer dev

# Individual services
php artisan serve          # Laravel server
php artisan queue:listen --tries=1  # Queue worker
php artisan pail --timeout=0        # Log viewer
npm run dev                          # Vite dev server

# Testing
composer test
php artisan test

# Code quality
./vendor/bin/pint          # PHP CS Fixer

API Application (api/)

# Development server with all services  
composer dev

# API documentation
# Access Swagger UI at: /api-docs/index.html (root redirects here)
# JSON spec at: /docs/api-docs.json

# Database
php artisan migrate
php artisan migrate:generate    # Generate migrations from existing DB

# Development tools
php artisan ide-helper:generate
php artisan ide-helper:models

Frontend Application (front/www/)

# CodeIgniter 3 application
composer install         # Install PHP dependencies
php -S localhost:8080    # Built-in development server

# Note: front/_Codeigniter/ contains the extracted CI3 system files
# Main application is in front/www/ directory

Build and Assets

# Frontend assets (both admin and api)
npm run build    # Production build
npm run dev      # Development with hot reload

# In individual directories
cd admin && npm run build
cd api && npm run build

API Structure & Authentication

Authentication Flow

1. API Key Authentication - All endpoints require valid API key via auth.apikey middleware
2. User Authentication - POST /v1/login returns Sanctum token
3. Protected Routes - Use auth:sanctum middleware for user-specific operations

Core API Endpoints (v1/)

• Auth: /v1/login, /v1/logout, /v1/signup
• Users: /v1/users/* - User management and profile operations
• Tenants: /v1/tenants/* - Multi-tenant operations and switching
• Admin: /v1/admin/* - Tenant user administration
• Products: /v1/products/* - Product catalog with BOM support
• Materials: /v1/materials/* - Material management
• Categories: /v1/categories/* - Hierarchical category management
• Files: /v1/file/* - File upload and management
• Design: /v1/design/* - Design workflow and versioning

Permission System

• Menu-based permissions with role inheritance
• Department-based access control
• Multi-level permission matrix (user → role → department → menu)

Database & Models

Multi-tenant Data Architecture

• Tenant isolation via tenant_id columns with BelongsToTenant global scope
• Shared models in shared/Models/ with tenant scoping
• Global admin tables for system management
• Soft deletes (deleted_at) applied across most entities
• Common audit columns: created_by, updated_by, deleted_by

Core Tables & Relationships

Authentication & Authorization

• api_keys - API key management with active status
• users - User accounts with soft deletes
• user_tenants - Many-to-many user-tenant relationships with active/default flags
• personal_access_tokens - Sanctum token storage
• permissions - Role-based permissions with tenant scoping
• roles - Tenant-scoped roles
• model_has_permissions/roles - Spatie permission assignments
• permission_overrides - Manual permission allow/deny with temporal validity

Multi-tenant Organization

• tenants - Company/organization master with subscription info
• tenant_user_profiles - Extended user profiles per tenant
• departments - Hierarchical organizational structure
• department_user - User-department assignments with primary department flag

Product Management

• categories - Hierarchical product categorization with soft deletes
• category_fields - Dynamic field definitions per category
• category_templates - Versioned category field snapshots
• products - Product catalog with type classification (PRODUCT/PART/SUBASSEMBLY)
• product_components - BOM relationships (MATERIAL|PRODUCT references)
• materials - Material master with dynamic attributes
• classifications - Flat code tables by group (product_type, payment_method, etc.)

Design & Manufacturing

• models - Design model master with lifecycle status
• model_versions - Versioned model releases with DRAFT/RELEASED status
• bom_templates - BOM templates linked to model versions
• bom_template_items - Template BOM line items with quantities and waste rates

Orders & Operations

• orders - Order/quotation master with workflow status
• order_items - Order line items with design codes
• order_item_components - Required materials/products per order item
• order_histories - Order change tracking and notes
• clients - Customer/vendor master

Inventory & Materials

• material_receipts - Incoming material receipts with lot tracking
• material_inspections - Quality inspection records
• material_inspection_items - Inspection checklist items
• lots - Material lot management
• lot_sales - Lot consumption tracking
• price_histories - Historical pricing with temporal validity

System & Configuration

• common_codes - Hierarchical master codes with tenant support
• files - Polymorphic file attachments
• audit_logs - Comprehensive audit trail with 13-month retention
• setting_field_defs - Global field definitions
• tenant_field_settings - Tenant-specific field configurations
• tenant_option_groups/values - Tenant-managed dropdown options

Content Management

• boards - Configurable board system
• posts - Board posts with custom fields
• board_settings - Dynamic field definitions per board
• board_comments - Hierarchical commenting system

Key Model Relationships

• Tenant → Users (many-to-many via user_tenants)
• Products ↔ Materials (via product_components with ref_type)
• Models → Versions → BOM Templates (design workflow)
• Orders → Items → Components (order breakdown)
• Categories ↔ Fields ↔ Templates (dynamic forms with versioning)
• Audit Logs (polymorphic tracking across all major entities)

Legacy Integration (5130/)

The 5130/ directory contains a large legacy PHP application for:

• Construction/manufacturing workflow management
• Equipment and material tracking
• Work order processing
• Financial calculations and reporting

Key legacy components:

• dbeditor/ - Database administration tools
• estimate/ - Cost estimation system
• output/ - Report generation
• Various specialized modules for construction processes

File Organization

Configuration

• Environment files: .env in each application directory
• Docker configs: docker/ directory
• Asset building: vite.config.js and tailwind.config.js in each app

Testing

• PHPUnit configuration: phpunit.xml in each Laravel app
• Test directories: tests/ in Laravel applications

Development Workflow

1. Environment Setup: Configure .env files for each application
2. Database: Run migrations in both admin and api applications
3. Dependencies: composer install and npm install in relevant directories
4. Development: Use composer dev to run all services concurrently
5. API Testing: Access Swagger documentation for API endpoints
6. Code Quality: Run Pint for PHP formatting

SAM API Development Rules

1. Architecture Philosophy

• Service First: All business logic must be written in Service classes (public functions)
• Controller: Only responsible for DI injection of Services and calling them. Use ApiResponse::handle() for responses
• Exception Flow: Errors are thrown → converted to JSON by global handler
• Context Enforcement: Base Service requires tenantId(), apiUserId(). Throws exception if not set

2. Multi-tenancy & Models

• BelongsToTenant global scope applied
• ModelTrait for is_active, date handling
• SoftDeletes by default
• Common columns: tenant_id, created_by, updated_by, deleted_by (COMMENT required)
• FK constraints: Created during design, minimal in production

3. Middleware Stack

• ApiKeyMiddleware, CheckSwaggerAuth, CorsMiddleware, CheckPermission, PermMapper
• Default route group: auth.apikey (some with auth:sanctum)

4. Routing (v1)

• Auth, Common codes, Files, Tenants, Users (me/tenants/switch), Menus+Permissions, Roles/Permissions, Departments, Field settings, Options, Categories, Classifications, Products, BOM
• REST conventions: index/show/store/update/destroy + extensions (toggle, bulkUpsert, reorder)

5. Controller/Service Rules

• Controller: FormRequest type-hint → only pass $request->validated() to Service
• Service: extends Service, tenantId()/apiUserId() required
• Lists: Pagination, explicit search parameters
• Responses: {success, message, data}, message must be i18n key only

6. i18n & Response Messages

• Messages: lang/{locale}/message.php
• Errors: lang/{locale}/error.php
• Rule: No direct strings, must use __('message.xxx'), __('error.xxx')
• Common keys: message.fetched/created/updated/deleted/bulk_upsert/reordered
• Resource-specific keys allowed: message.product.created, message.bom.bulk_upsert

7. Swagger Documentation (l5-swagger 9.0)

• Tags: Resource-based (User, Auth, Product, BOM...)
• Security: ApiKeyAuth + BearerAuth
• Schemas: Reuse ApiResponse, ErrorResponse, resource DTOs
• Specifications: Clear Path/Query/Body parameters with examples
• No duplicate schemas, accurate nullable/oneOf distinctions

8. Validation (FormRequest)

• No direct validate() calls. Separate all into FormRequest classes
• Reuse common Requests: PaginateRequest, BomItemsRequest, DateRangeRequest
• Boundary validation (effective_from ≤ effective_to) in Request

9. Audit Logging

• Table: audit_logs (tenant_id, target_type, target_id, action, before/after(json), actor_id, ip, ua, created_at)
• Actions: created, updated, deleted, released, cloned, items_replaced, diff_viewed
• Retention: 13 months default, audit:prune scheduler cleanup
• Failure tolerance: Log failures don't block business operations

10. Domain Rules

• Status: Strings (DRAFT/RELEASED/ARCHIVED)
• Unique/Indexes: models(code), model_versions(version_no), bom_items(parent, order)
• BOM: Supports summary/validate/bulkUpsert/reorder

11. Commit Messages

• Format: [type]: title + detailed bullets
• Types: feat | fix | chore | refactor | style
• Example: feat: 감사 로그 도입 및 스케줄러 추가

Design/Estimation/Ordering Domain

Parameter-based BOM Resolution

• Input Parameters: W0/H0, installation type, power source, etc.
• Output Preview: W1/H1, area, weight, motor, bracket, guide, case, bottom, shaft, pipe (auto-calculated)
• Rules: Product family-specific formulas (Screen/Steel), boundary values apply higher capacity
• Proposed APIs:
  • GET /design/models/{id}/parameters → Returns input schema
  • POST /design/models/{id}/bom/resolve → BOM/item calculation preview based on input values

Git Repository Structure & Workflow

Multiple Repository Setup

This project uses 5 separate Git repositories for different components:

• api/ - API project repository
• admin/ - Laravel admin panel repository
• front/www/ - CodeIgniter frontend repository
• front/_Codeigniter/ - Extracted CI3 system files repository
• shared/ - Shared models and services (planned for future use when API is mature)

Work Tracking & Commit Workflow

1. Work Tracking: All ongoing work is documented in CURRENT_WORKS.md at the root level
2. Progress Updates: As features are developed, update CURRENT_WORKS.md with changes per repository
3. Commit Process: When a feature is complete:
   • Organize completed work by repository (api, admin, front/www, front/_Codeigniter, shared)
   • Update CURRENT_WORKS.md with summary of modified/added/deleted files
   • Create Git commits in each affected repository
   • If CURRENT_WORKS.md doesn't exist, create it and add to Git

Repository-Specific Operations

Each repository operates independently with its own:

• Git history and branches
• Environment configuration (.env files)
• Dependencies and build processes
• Deployment workflows

Project Workflow Management

CLAUDE.md File Synchronization

This project uses multiple CLAUDE.md files for better workspace management:

1. Master File: /SAM/CLAUDE.md - Contains comprehensive project documentation
2. Local Copies: Each repository has its own CLAUDE.md for focused development

Synchronization Rules:

• At session start: Compare timestamps and update master file if local is newer
• When working: Use local CLAUDE.md for repository-specific guidance
• Before commit: Ensure synchronization is complete

Work Tracking System

CURRENT_WORKS.md Structure

# SAM 프로젝트 작업 현황

## YYYY-MM-DD (요일) - 작업 제목

### 주요 작업
- 작업 항목들 나열

### 저장소별 작업 내용

#### API 저장소 (`/api`)
**수정된 파일:**
- 파일명 - 변경 내용

**삭제된 파일:**
- 파일명 - 삭제 이유

**추가된 파일:**
- 파일명 - 추가 목적

**작업 내용:**
- 상세한 작업 설명
- 마이그레이션 상태 변경사항
- 환경 설정 변경사항

#### [다른 저장소들도 동일한 구조로]

Git Commit Workflow

# 1. 작업 완료 후 CURRENT_WORKS.md 업데이트
# 2. 각 저장소별 커밋
cd api && git add . && git commit -m "feat: 작업 내용"
cd ../admin && git add . && git commit -m "feat: 작업 내용"
cd ../front/www && git add . && git commit -m "feat: 작업 내용"

# 3. 커밋 메시지 형식
# [type]: 간결한 제목
#
# - 상세 변경 내용 (필요시)
# - 브레이킹 체인지 (있는 경우)
#
# 🤖 Generated with [Claude Code](https://claude.ai/code)
# Co-Authored-By: Claude <noreply@anthropic.com>

Commit Types

• feat: 새로운 기능 추가
• fix: 버그 수정
• docs: 문서 변경
• style: 코드 포맷팅, 세미콜론 누락, 코드 변경이 없는 경우
• refactor: 프로덕션 코드 리팩토링
• test: 테스트 추가, 테스트 리팩토링
• chore: 빌드 테스크 업데이트, 패키지 매니저 설정 등

Session Management Best Practices

Session Start

1. Check Docker services are running
2. Compare CLAUDE.md files and sync if needed
3. Review CURRENT_WORKS.md for context
4. Check Git status in all repositories
5. Verify database migration status

During Work

1. Update CURRENT_WORKS.md regularly
2. Commit frequently with descriptive messages
3. Run tests before committing
4. Keep CLAUDE.md local copy updated with new insights

Session End

1. Final CURRENT_WORKS.md update
2. Commit all pending changes
3. Push critical changes to remote (if needed)
4. Sync CLAUDE.md files
5. Clean up temporary files

Database Migration Management

# Check current status
php artisan migrate:status

# Run pending migrations
php artisan migrate

# Rollback specific steps (for debugging)
php artisan migrate:rollback --step=N

# Reset to specific commit state
# 1. First rollback migrations to target state
# 2. Then git reset to target commit
# 3. Finally run migrations up to target state

Important Notes

• The system uses Laravel 12 with PHP 8.2+
• Filament v3 is used for admin panel interface
• TailwindCSS for styling with Vite for asset building
• Sanctum for API authentication
• Multi-tenant architecture requires proper tenant context in all operations
• Follow SAM API Development Rules strictly when working on API-related tasks
• Always maintain CURRENT_WORKS.md for project continuity
• Sync CLAUDE.md files between sessions for consistency