Java Spring Boot Service Readme generator

Act as an expert at reading code and generating documentation for Java Spring Boot services.

Your task is to write a detailed, well-structured, and highly informative README.md file for this internal/private Java Spring Boot service repository.

Leverage your access to the repository to automatically gather the necessary context. This includes:

• Inspecting the pom.xml (or build.gradle) for dependencies and Java versions.
• Analyzing relevant configuration files (e.g., application.yml, application.properties).
• Reading the CODEOWNERS file to identify project owners/maintainers.
• Scanning for common Spring Boot patterns, API endpoints, and potential KEDA configurations.
• Considering any existing README.md file in the repository. Integrate any important points from it into the new structure, enhancing or correcting them as needed. Only include a separate "Miscellaneous Notes" section at the end if information cannot be categorized elsewhere.

README Structure

Generate the README with the following mandatory sections and information:

1. Service Overview

• Project Name: Automatically determine the project name.
• Purpose/Problem Solved: Based on code analysis and common project patterns, infer the primary business purpose and what problem this service addresses within the organization.
• Key Features/Functionality: Identify and list the main functionalities and features the service provides.

2. Table of Contents

Generate a clear and clickable Table of Contents at the beginning of the README, linking to all major sections.

3. Technologies & Service Dependencies

• Core Technologies: List the main programming languages (specifically Java version), frameworks (Spring Boot version), and key libraries identified from the build configuration (e.g., Maven/Gradle, Lombok, common Spring starters).
• External/Internal Service Dependencies: Analyze the codebase for connections to databases (e.g., PostgreSQL, MySQL), message queues (e.g., Kafka, RabbitMQ), other internal microservices, or external APIs. Clearly list these dependencies.
• Other Tools: Identify and list other significant tools or platforms used (e.g., Docker, Kubernetes).

4. Setup & Local Development

Provide clear, step-by-step instructions on how to set up and run the service locally for development.

• Prerequisites: Automatically detect and list necessary prerequisites (e.g., specific JDK version, Maven/Gradle).
• Obtaining the Repository's Code: Provide the standard git clone command for the current repository.
• Initial Setup/Build: Provide the exact commands to build the project (e.g., mvn clean install, gradle build).
• Configuration: Explain how to manage environment variables or application properties for local development. Suggest a .env.local or application-local.properties approach if common.
• Running Locally: Provide the exact commands to start the application in development mode (e.g., mvn spring-boot:run, java -jar target/<your-service>.jar).
• Database Setup (if applicable): If database interactions are detected, provide general instructions for setting up a local database instance or connecting to a dev database, assuming common practices.

5. KEDA Scaling Logic

Automatically identify and explain any KEDA (Kubernetes Event-driven Autoscaling) configuration relevant to this service.

If found, detail:

• Scaler Type(s): (e.g., Kafka, SQS, Prometheus, HTTP).
• Trigger Details: Describe the specific trigger configuration (e.g., scales based on Kafka topic lag, HTTP requests).
• Min/Max Replicas: The minimum and maximum replica counts.
• Thresholds: Any specific scaling thresholds (e.g., target average lag).
• Relevant Configuration Files: Provide the path to the KEDA ScaledObject definition within the repository.

If no KEDA configuration is found, state that KEDA scaling is not explicitly configured in the repository.

6. Monitoring

a. ArgoCD:

• Provide general guidance on verifying deployment status and health in ArgoCD.
• Suggest a placeholder for the ArgoCD Application Name/Link: [ArgoCD Application Link for this service].

b. Grafana:

• Suggest common categories of Grafana Dashboards relevant for a Spring Boot service (e.g., "Service Health," "JVM Metrics," "API Performance," "Database Performance").
• Provide placeholders for specific Grafana Dashboard Links: [Service Health Dashboard Link], [JVM Metrics Dashboard Link].
• List important metrics to watch based on common Spring Boot monitoring practices and detected dependencies (e.g., HTTP request latency, error rate, JVM heap usage, database connection pool, Kafka consumer lag).
• Suggest a placeholder for key alerts: [Key Alerts configured for this service].

7. Service Documentation

API Endpoints:

• Analyze the code to identify and document main API endpoints (path, HTTP method, brief description).
• Provide generic examples of request bodies and sample responses based on common Spring Boot REST controller patterns.
• Mention any detected authentication/authorization mechanisms.

Swagger/OpenAPI Documentation:

If Swagger/OpenAPI annotations or configurations are detected, instruct on how to access the documentation locally (e.g., http://localhost:8080/swagger-ui.html or http://localhost:8080/v3/api-docs). Provide a placeholder for deployed environments: [Internal Deployment Swagger/OpenAPI Link].

Other Internal Documentation:

Suggest a placeholder for links to any other relevant internal documentation (e.g., [Confluence Design Document Link]).

8. Project Structure & Key Files

• Analyze the repository and provide a concise overview of the main directories and their purpose.
• Highlight key configuration files, important source code directories, and entry points relevant to a Spring Boot application.

9. Testing

• Explain how to run tests for the project locally. Automatically detect the relevant commands (e.g., mvn test, gradle test).
• Mention any testing frameworks detected (e.g., JUnit, Mockito, Spring Boot Test).

10. Owners & Support

• Primary Contacts/Squad: Infer the primary team or squad responsible for this service (if possible, based on project name or common internal conventions), otherwise, provide a placeholder. Suggest a placeholder for internal chat channels: [Internal Chat Channel, e.g., Slack channel #project-name].
• Codeowners/Maintainers: Read the CODEOWNERS file in the repository. List the specific individuals or teams designated as codeowners for different parts of the repository, along with their preferred internal contact info if inferable or provide placeholders.
• Issue Tracking: Suggest a placeholder for the internal issue tracking system: [Link to Internal Issue Tracking System (e.g., Jira)].

11. Known Issues / Caveats (Optional but Recommended)

Provide a placeholder for any known bugs, limitations, or peculiar behaviors that developers should be aware of.

12. Diagrams / Architecture (Optional)

Suggest a placeholder for embedding architecture diagrams or flowcharts that explain the system's interaction with other internal services.

Formatting Notes:

• Use Markdown effectively with clear headings, subheadings, bold text, code blocks, and lists.
• Focus on providing clear instructions and information that developers can immediately use.
• Avoid overly verbose explanations.
• Use concrete examples for commands, paths, and URLs where applicable, derived from the repository content.