This PR significantly enhances the .github/copilot-instructions.md file to include comprehensive Javalin patterns, design philosophy, and best practices. The improvements will help AI assistants (like GitHub Copilot) generate correct, idiomatic Javalin code.

What's Changed

The documentation has been expanded from 152 to 859 lines with the following new sections:

Core Philosophy & Principles

Added clear explanation of Javalin's design philosophy:

• No Annotations - All configuration is code-based
• No Reflection - Everything is explicit and statically typed
• No Magic - Plain, understandable code
• Functional First - Heavy use of lambdas and functional interfaces
• Consumer-based Configuration - All config uses Consumer<Config> pattern

Comprehensive Pattern Documentation

Configuration Patterns - Shows consumer-based configuration, nested hierarchy, and proper use of config objects (http, router, staticFiles, events)

Handler Patterns - Functional interface handlers with lambdas and method references, emphasizing Javalin 7's config.routes API

Routing Patterns - Documents both routing styles:

• Direct routing: config.routes.get/post/delete/etc()
• ApiBuilder for nested structures: config.routes.apiBuilder(() -> { ... })

Lifecycle Management - Before/after handlers, beforeMatched, exception handlers (preferred over try-catch), and error handlers

Context Usage - Comprehensive examples of request data access and response building patterns

Plugin Patterns - Using bundled plugins, creating custom plugins, and context-extending plugins

WebSocket Patterns - Event handlers (onConnect, onMessage, onClose, onError) and JSON over WebSocket

Async Patterns - CompletableFuture support and virtual threads (Java 21+)

JSON Patterns - Built-in Jackson support, serialization/deserialization examples

Anti-Patterns Section

Documents what NOT to do with clear examples:

• ❌ Don't use annotations (Javalin is annotation-free)
• ❌ Don't extend classes (no base class inheritance needed)
• ❌ Don't use reflection (everything is explicit)
• ❌ Don't use old Javalin 6 API (app.get() method chaining)
• ❌ Don't catch everything (use exception handlers instead)

Testing Patterns & Best Practices

• TestUtil usage for integration tests
• Unit testing with mocks
• 10-point best practices summary

Validation

To ensure accuracy, this PR includes:

• New test file: CopilotInstructionsPatternValidation.java that validates all documented patterns compile correctly
• All examples use the correct Javalin 7 API (config.routes instead of deprecated method chaining)
• Build passes successfully with all examples

Impact

These improvements will help AI assistants:

• Generate correct, idiomatic Javalin 7 code
• Understand Javalin's functional, annotation-free philosophy
• Avoid common mistakes and deprecated patterns
• Follow established best practices
• Create maintainable, production-ready code

The documentation is now fully aligned with:

• Javalin 7 API
• Official documentation at https://javalin.io/documentation
• Framework philosophy (no magic, no reflection, functional first)
• Real codebase examples from /javalin/src/test/kotlin/io/javalin/examples/

Closes #XXXX

Fixes #2482

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.