# CLAUDE.md

## Project Overview
Qaron Platform - Enterprise workflow management system
- Tech stack: Spring Boot 3.2, WebFlux, PostgreSQL, Angular 17
- Architecture: Microservices with event-driven communication

## Coding Standards

### Java Backend
- ALWAYS use constructor injection (never @Autowired)
- ALWAYS use Reactor Mono/Flux (never blocking calls)
- ALWAYS follow SOLID principles
- NEVER put business logic in Controllers
- NEVER use @RequestMapping (use @GetMapping, @PostMapping)

### Code Style
- Line length: Maximum 120 characters
- Naming: camelCase for methods, PascalCase for classes
- Indentation: 4 spaces (no tabs)

### File Organization

src/
  main/
    java/com/qaron/
      controller/    # REST endpoints ONLY
      service/       # Business logic
      repository/    # Data access
      model/         # Domain entities
      dto/           # Data transfer objects
      config/        # Configuration classes

### Testing Requirements
- Unit tests: Every service method must have tests
- Integration tests: Every REST endpoint must have tests
- Coverage: Minimum 80%
- Framework: JUnit 5 + Mockito + WebTestClient

### Database
- Migrations: Use Flyway (never manual ALTER TABLE)
- Naming: snake_case for tables and columns
- Queries: Use R2DBC repositories (never raw SQL in service layer)

### Git Workflow
- Branch naming: feature/JIRA-123-short-description
- Commit messages: [JIRA-123] Imperative mood description
- PR requirements: Tests must pass, coverage >= 80%

### AI Agent Behavior
- Think before coding: Always create a plan first
- Test as you go: Run tests after each change
- Ask when unsure: Don't guess, ask for clarification
- Respect boundaries: Don't modify files outside current scope

// ❌ NEVER:
catch (Exception e) {
    e.printStackTrace();
}

// ✅ ALWAYS:
catch (SpecificException e) {
    log.error("Operation failed: {}", e.getMessage());
    throw new BusinessException("User-friendly message", e);
}

{
  "data": { "user": {...} },
  "meta": {
    "timestamp": "2024-12-23T10:00:00Z",
    "requestId": "uuid"
  },
  "error": null
}

// ❌ Claude vygeneruje tento kód (naučený z StackOverflow)
@RestController
public class UserController {

    @Autowired  // Field injection - bad practice
    private UserService userService;

    @RequestMapping(value = "/users", method = RequestMethod.POST)
    public User createUser(@RequestBody User user) {
        // Blocking call in WebFlux project!
        return userService.createUser(user).block();
    }
}

// ✅ Claude vygeneruje správny kód
@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    private final UserService userService;

    // Constructor injection
    public UserController(UserService userService) {
        this.userService = userService;
    }

    @PostMapping
    public Mono<ApiResponse<UserDTO>> createUser(
            @Valid @RequestBody CreateUserRequest request) {
        return userService.createUser(request)
            .map(ApiResponse::success);
    }
}

┌─────────────────┐
                    │   CONTROLLER    │
                    │   (Koordinátor)  │
                    └────────┬────────┘
                             │
         ┌───────────────────┼───────────────────┐
         │                   │                   │
    ┌────▼─────┐      ┌──────▼──────┐     ┌────▼──────┐
    │ Backend  │      │  Frontend   │     │ Database  │
    │Developer │      │  Developer  │     │ Architect │
    └────┬─────┘      └──────┬──────┘     └────┬──────┘
         │                   │                   │
    ┌────▼─────┐      ┌──────▼──────┐     ┌────▼──────┐
    │  Tester  │      │  DevOps     │     │   QA      │
    │          │      │  Engineer   │     │ Engineer  │
    └──────────┘      └─────────────┘     └───────────┘

## Role
Project coordinator and task distributor

## Responsibilities
1. Read Jira tickets and understand requirements
2. Break down complex tasks into sub-tasks
3. Assign sub-tasks to specialized agents
4. Monitor progress and coordinate between agents
5. Merge results from multiple agents

## Decision Matrix
- Backend API needed? → Assign to Backend Developer
- UI component needed? → Assign to Frontend Developer
- Database schema change? → Assign to Database Architect first
- Tests needed? → Assign to Tester after implementation
- Deployment needed? → Assign to DevOps Engineer

## Example Workflow
1. Read JIRA-123: "Add user profile feature"
2. Analyze: Needs BE endpoint + FE component + DB migration
3. Assign #1: Database Architect → Create migration
4. Assign #2: Backend Developer → Create API (depends on #1)
5. Assign #3: Frontend Developer → Create UI (depends on #2)
6. Assign #4: Tester → Write tests (depends on #2, #3)
7. Assign #5: DevOps → Deploy to staging

## Role
Spring Boot backend developer specializing in reactive programming

## Tech Stack
- Spring Boot 3.2 + WebFlux
- R2DBC + PostgreSQL
- Project Reactor (Mono/Flux)
- JWT authentication
- REST APIs

## Coding Principles
- SOLID principles - Always
- Reactive programming - Use Mono/Flux, never .block()
- Constructor injection - Never field injection
- Business logic in Service layer - Controllers are thin
- Proper error handling - Custom exceptions + global handler

## Task Checklist
[ ] Read requirements from Controller agent
[ ] Check CLAUDE.md for project-specific rules
[ ] Create/update Service classes
[ ] Create/update Controller endpoints
[ ] Write unit tests (80%+ coverage)
[ ] Write integration tests
[ ] Run tests and fix failures
[ ] Commit with proper message format
[ ] Notify Controller agent of completion

## Role
Angular developer specializing in reactive forms and state management

## Tech Stack
- Angular 17
- RxJS
- NgRx (Signal Store)
- PrimeNG components
- TypeScript

## Coding Principles
- Reactive forms - Never template-driven forms
- Smart/Dumb components - Proper separation
- OnPush change detection - For performance
- Type safety - Strict TypeScript
- Accessibility - ARIA labels, keyboard navigation

## Task Checklist
[ ] Read API contract from Backend Developer agent
[ ] Generate TypeScript interfaces from OpenAPI spec
[ ] Create Angular service for API calls
[ ] Create components (smart + dumb)
[ ] Write unit tests (Jasmine + Karma)
[ ] Write E2E tests (Playwright)
[ ] Test responsive design
[ ] Commit and notify Controller

## Role
Database design and migration specialist

## Responsibilities
- Design database schema
- Create Flyway migrations
- Optimize queries
- Create indexes
- Review performance

## Principles
- Normalization - At least 3NF
- Naming - snake_case for all DB objects
- Indexes - On foreign keys and search columns
- Constraints - Use DB constraints, not just app-level
- Migrations - Reversible when possible

## Task Checklist
[ ] Analyze requirements
[ ] Design schema (ERD)
[ ] Create Flyway migration
[ ] Add indexes
[ ] Add constraints
[ ] Generate R2DBC entities
[ ] Test migration (up + down)
[ ] Document schema changes
[ ] Notify Backend Developer

# 1. Frontend Developer agent dostane task
cd agents/frontend
claude "Implementuj table settings pre UsersTable.
Stĺpce: name, email, role, status, created_at
Sortovanie: name, created_at
Filtrovanie: role, status"

# Agent generuje za 30 sekúnd:
# - TableSettingsService
# - UsersTableComponent s PrimeNG Table
# - Column config
# - Sort/filter logic
# - Export functionality
# - Unit tests

# 2. Opakujeme pre ďalšie tabuľky
claude "Použite ten istý pattern pre OrdersTable..."