Enhance Copilot instructions with best practices and code examples

[Copilot]

The existing .github/copilot-instructions.md provided basic project context but lacked rationale, concrete examples, and actionable guidance for effective AI assistance.

Changes

Architecture & Principles

• Added "Why" explanations for data flow patterns (H2-first, BIAN enrichment, circuit breaker fallback)
• Documented package structure rationale (separation of concerns, DTO boundaries)

Code Patterns (✅ Good vs ❌ Avoid)

Added comparative examples for:

• Backend: Lombok usage, constructor injection, ResponseEntity wrappers, circuit breaker patterns, JPA query optimization
• Frontend: Functional components, React Query for server state, theme centralization, React Router v7 syntax

Example pattern added:

// ✅ Good: Service with resilience
@CircuitBreaker(name = "bianApi", fallbackMethod = "getTransactionsFallback")
@Retry(name = "bianApi")
public List<TransactionDto> getCardTransactions(Long cardId) {
    return fetchFromBianApi(cardId);
}

public List<TransactionDto> getTransactionsFallback(Long cardId, Exception ex) {
    log.warn("Using fallback for card id: {} due to: {}", cardId, ex.getMessage());
    return getSampleTransactions(cardId);
}

Testing Guidelines

• MockMvc controller tests with @WebMvcTest isolation
• Service layer mocking patterns with @ExtendWith(MockitoExtension.class)
• Playwright E2E structure with fixture-based API mocking

Environment Configuration

• Complete application.yml with Resilience4j tuning
• Vite environment variable patterns
• Docker environment variable injection examples

Quick Reference

• Common commands (build, test, run)
• Key endpoints (API, H2 console, OpenAPI docs)
• Troubleshooting guide (port conflicts, dependency issues, test failures)

Best Practices Checklist

Actionable pre-commit, coding, and testing checklists for consistent workflows

---

Impact: 665 lines added (126 → 791), providing comprehensive context for AI-assisted development while maintaining project-specific conventions.

Original prompt

Objective

Update the .github/copilot-instructions.md file to follow best practices from the customize-your-repo guide, making it more comprehensive and effective for GitHub Copilot.

Current State

The existing .github/copilot-instructions.md file is functional but could be significantly improved by:

• Adding rationale ("why") for each guideline
• Including concrete ✅ Good vs ❌ Avoid code examples
• Expanding testing patterns
• Clarifying environment configuration
• Adding quick reference sections
• Organizing content more logically

Required Changes

Replace the entire contents of .github/copilot-instructions.md with the following improved version:

# Copilot Instructions for Three Rivers Bank Credit Card Website

## Project Overview
This is a full-stack business credit card comparison platform for Three Rivers Bank. The application demonstrates modern banking software architecture with resilient API integration patterns. We prioritize reliability and clear separation of concerns over cutting-edge experimental features.

## Tech Stack

### Backend
- **Spring Boot 3.2.0** with Java 17
- **H2 In-Memory Database** (primary data source)
- **Spring Data JPA** with Hibernate
- **OpenFeign** for HTTP clients (BIAN API integration)
- **Resilience4j** for circuit breaker patterns
- **Spring Cache Abstraction** (5min/1hr TTL)
- **SpringDoc OpenAPI** for API documentation
- **Lombok** for boilerplate reduction
- **Maven** for dependency management

### Frontend
- **React 19.2** (functional components only)
- **Vite 7.x** for build tooling
- **React Router v7** for navigation
- **TanStack Query** for server state management
- **Material-UI (MUI) v7** for UI components
- **Axios** for HTTP client
- **ESLint** with React Hooks plugin

### Infrastructure
- **Docker** multi-stage builds (Alpine-based)
- **Nginx** for serving frontend in production
- **Azure Container Apps** deployment target
- **GitHub Actions** for CI/CD
- **Playwright** for E2E testing

## Architecture Principles

### Data Flow (Critical Path)
```
Frontend → Backend REST API → H2 Database (always first)
                             ↓
                     BIAN API (optional enrichment)
                             ↓
                     Circuit Breaker → H2 fallback
                             ↓
                     Cache Response
                             ↓
                     Return DTO
```

**Why:** H2 contains our product catalog (the source of truth). BIAN API provides supplementary transaction/billing data but may be unreliable. This pattern ensures the application remains functional even when external APIs fail.

### Backend Package Structure
```
com.threeriversbank/
├── controller/          # REST endpoints (thin layer)
├── service/             # Business logic
├── repository/          # JPA repositories
├── model/
│   ├── entity/         # JPA entities
│   └── dto/            # Data transfer objects
├── client/             # Feign clients for external APIs
└── config/             # Spring configuration classes
```

**Why:** Clear separation of concerns. Controllers handle HTTP, services contain business logic, repositories abstract database access. DTOs prevent entity leakage to API consumers.

## Code Style

### Java/Spring Boot Patterns

#### Use Lombok Annotations
✅ **Good:**
```java
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class CreditCardDto {
    private Long id;
    private String name;
    private BigDecimal annualFee;
}
```

❌ **Avoid:**
```java
public class CreditCardDto {
    private Long id;
    private String name;
    
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    // ... manual getters/setters
}
```

**Why:** Lombok reduces boilerplate by 60-80% in our DTOs and entities. Our build pipeline already includes the Lombok processor.

#### Controller Best Practices
✅ **Good:**
```java
@RestController
@RequestMapping("/api/cards")
@RequiredArgsConstructor
@Slf4j
@Tag(name = "Credit Cards", description = "Three Rivers Bank Business Credit Card API")
public class CreditCardController {
    
    private final CreditCardService creditCardService;
    
    @GetMapping("/{id}")
    @Operation(summary = "Get credit card by ID")
    public ResponseEntity<CreditCardDto> getCardById(@PathVariable Long id) {
        log.info("GET /api/cards/{}", id);
        CreditCardDto card = creditCardService.getCreditCardById(id);
        return ResponseEntity.ok(card);
    }
}
```

❌ **Avoid:**
```java
@RestController
public class CreditCardController {
    
    @Autowired
    private CreditCardService creditCardService;
    
    @GetMapping("/api/cards/{id}")
    public CreditCardDto getCardById(@PathVariable Long id) {
        // No logging, no OpenAPI annotations, no ResponseEntity wrapper
        return creditCardService.getCreditCardById(id);
    }
}
```

**Why:** 
- `@RequiredArgsConstructor` with final fields is preferred over `@Autowired`
- Centralize...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>

<!-- START COPILOT CODING AGENT TIPS -->
---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey).