TEXT

Technical Codebase Discovery & Onboarding Prompt

Contributed by valdecir.carvalho@gmail.com

Improved by Laravel Company · 2026-09-07

Project Onboarding Guide: Technical Deep Dive

Context

As a newly integrated developer on this project, your primary objective is to gain a deep understanding of the existing codebase as quickly as possible. This guide will serve as a comprehensive technical onboarding tool, providing a detailed, clear, and well-structured Markdown document that explains the system’s architecture, features, main flows, key components, and technology stack. The document will include direct links to relevant files, classes, and functions, along with code examples to enhance clarity.

Detailed Instructions

1. README / Instruction Files Summary

1.1 Project Overview

The Project Name is a scalable Microservices architecture built using Java (version 17) and the Spring Boot framework (version 2.5.2). It handles customer orders for a retail company, supporting a high volume of concurrent requests.

1.2 Setup Instructions

  • Cloning the repository: Use the command git clone https://github.com/org/project.git.
  • Setting up the database: The system uses PostgreSQL version 13.2. The connection details are configured in the application.properties file located at src/main/resources.
  • Running the application: Execute ./mvnw spring-boot:run from the project root directory.

1.3 Adopted Standards and Conventions

  • The project follows the Spring Boot naming conventions for packages and files.
  • Java code adheres to the Google Java Format style.
  • Commenting is done using Javadoc for public API and JavaDoc for internal documentation.

2. Detailed Technology Stack

2.1 Programming Language and Frameworks

  • Java: version 17.0.1
  • Spring Boot: version 2.5.2
    • Spring Web: version 5.3.9
    • Spring Data JPA: version 2.5.2
    • Spring Security: version 5.4.7
    • Spring Boot Starter Actuator: version 2.5.2
  • Hibernate: version 5.5.8.Final

2.2 Database

  • PostgreSQL: version 13.2
  • Database Driver: PostgreSQL JDBC Driver (version 42.2.23)

2.3 Build Tools

  • Apache Maven: version 3.6.3
  • Maven Wrapper: version 3.8.4

2.4 Other Relevant Technologies

  • Lombok: version 1.18.22 (for boilerplate reduction)
  • OpenFeign: version 11.0 (for REST client)
  • JUnit: version 5.7.1 (for unit testing)
  • Mockito: version 3.11.2 (for mocking dependencies)
  • Log4j2: version 2.14.1 (logging library)

3. System Overview and Purpose

3.1 Core Functionality

The system is designed to handle high-volume order processing for a retail company. It provides a RESTful API for customers to place, cancel, and track their orders. The API also manages inventory levels and updates in real-time.

3.2 Main Features

  • Order Placement: Customers can create new orders with multiple items.
  • Order Tracking: Customers can view the status of their orders (e.g., pending, processing, shipped, delivered).
  • Inventory Management: The system automatically updates inventory levels as orders are processed.
  • Security: All API endpoints are secured using JWT (JSON Web Tokens) authentication.

4. Project Structure and Reading Recommendations

4.1 Entry Point

The main entry point for the application is the class located at src/main/java/com/project/Application.java. This file initializes the Spring Boot application context.

4.2 General Organization

The project follows a standard MVC (Model-View-Controller) architecture:

  • Controller: Located under src/main/java/com/project/controller/
  • Service: Located under src/main/java/com/project/service/
  • Repository: Located under src/main/java/com/project/repository/
  • Model: Located under src/main/java/com/project/model/
  • DTO: Located under src/main/java/com/project/dtos/
  • Util: Located under src/main/java/com/project/utils/
  • Config: Located under src/main/java/com/project/config/

4.3 Configuration Files

  • The main configuration file is application.properties, located at src/main/resources/.
  • It contains database connection details, server port settings, and other general configuration parameters.

4.4 Reading Recommendation

To quickly grasp the project’s core concepts, I recommend starting with the following key files:

  1. src/main/java/com/project/Application.java (main entry point)
  2. src/main/java/com/project/model/Order.java (represents the core business entity)
  3. src/main/java/com/project/repository/OrderRepository.java (defines the repository interface)
  4. src/main/java/com/project/service/OrderService.java (implements the business logic)
  5. src/main/java/com/project/controller/OrderController.java (the REST API entry point)

5. Key Components

5.1 OrderServiceImpl

The OrderServiceImpl class is the central component responsible for order-related business logic. It processes orders, validates data, and interacts with the repository. Link: OrderServiceImpl.java

Representative Code Snippet:

java
public Order createOrder(OrderDTO orderDTO) {
  // Validate order data
  if (orderDTO.getItems().isEmpty()) {
    throw new OrderValidationException("At least one item is required");
  }

  // Convert DTO to Order entity
  Order order = orderMapper.toEntity(orderDTO);

  // Save the order to the database
  Order savedOrder = orderRepository.save(order);

  // Return the saved order
  return savedOrder;
}

5.2 OrderRepository

The OrderRepository interface defines the database operations for the Order entity. It extends the JpaRepository interface provided by Spring Data JPA. Link: OrderRepository.java

6. Execution and Data Flows

6.1 Order Processing Workflow

Here is a high-level overview of the order processing workflow:

  1. The customer sends an order creation request to the /orders endpoint.
  2. The OrderController receives the request and validates the input data.
  3. The OrderController delegates the processing to the OrderService.
  4. The OrderService validates the order data and converts the DTO to an Order entity.
  5. The OrderService saves the Order entity to the database using the OrderRepository.
  6. The OrderService updates the inventory levels for each item in the order.
  7. The OrderService publishes an order creation event to the message broker (if configured).
  8. The OrderController returns the created order to the client.

6.2 Database Schema Overview

The database schema consists of a single main table: orders. The table has the following columns:

  • id (Primary Key)
  • customer_id (Foreign Key to the customers table)
  • order_status (ENUM: PENDING, PROCESSING, SHIPPED, DELIVERED)
  • order_date (Timestamp)
  • total_amount (Decimal)

6.3 Diagram: Order Processing Flow

mermaid
graph LR;
  A[Create Order (Client)] --> B[Order Controller];
  B --> C[Order Service];
  C --> D[Order Repository];
  C --> E[Inventory Service];
  C --> F[Message Broker (Event)];
  D --> G[Database];
  E --> G;
  C --> H[Return Created Order];
  H --> I[Client];

7. Dependencies and Integrations

7.1 Dependencies

  • Spring Boot Starter Web: Provides the Spring MVC framework for building RESTful services.
  • Spring Boot Starter Data JPA: Provides integration with the PostgreSQL database using the Hibernate ORM.
  • Spring Security: Provides authentication and authorization functionality using JWT.
  • Lombok: Automatically generates boilerplate code (getters, setters, equals, hashCode, etc.).

7.2 Integrations

The system currently has no external integrations. However, there are stubs for inventory management and message broker integration (if configured), which are planned for future development.

7.3 API Documentation

The project uses the OpenAPI standard for API documentation. The OpenAPI specification is located at src/main/resources/openapi/openapi.yaml. It can be viewed using tools like Swagger or Postman.

8. Diagrams

8.1 Component Diagram

mermaid
graph LR;
  A[Client] --> B[Order Controller];
  B --> C[Order Service];
  C --> D[Order Repository];
  C --> E[Inventory Service];
  D --> F[Database];
  E --> F;

8.2 Data Flow Diagram

mermaid
Original prompt (before our improvements)

**Context:** I am a developer who has just joined the project and I am using you, an AI coding assistant, to gain a deep understanding of the existing codebase. My goal is to become productive as quickly as possible and to make informed technical decisions based on a solid understanding of the current system. **Primary Objective:** Analyze the source code provided in this project/workspace and generate a **detailed, clear, and well-structured Markdown document** that explains the system’s architecture, features, main flows, key components, and technology stack. This document should serve as a **technical onboarding guide**. Whenever possible, improve navigability by providing **direct links to relevant files, classes, and functions**, as well as code examples that help clarify the concepts. --- ## **Detailed Instructions — Please address the following points:** ### 1. **README / Instruction Files Summary** - Look for files such as `README.md`, `LEIAME.md`, `CONTRIBUTING.md`, or similar documentation. - Provide an objective yet detailed summary of the most relevant sections for a new developer, including: - Project overview - How to set up and run the system locally - Adopted standards and conventions - Contribution guidelines (if available) --- ### 2. **Detailed Technology Stack** - Identify and list the complete technology stack used in the project: - Programming language(s), including versions when detectable (e.g., from `package.json`, `pom.xml`, `.tool-versions`, `requirements.txt`, `build.gradle`, etc.). - Main frameworks (backend, frontend, etc. — e.g., Spring Boot, .NET, React, Angular, Vue, Django, Rails). - Database(s): - Type (SQL / NoSQL) - Name (PostgreSQL, MongoDB, etc.) - Core architecture style (e.g., Monolith, Microservices, Serverless, MVC, MVVM, Clean Architecture). - Cloud platform (if identifiable via SDKs or configuration — AWS, Azure, GCP). - Build tools and package managers (Maven, Gradle, npm, yarn, pip). - Any other relevant technologies (caching, message brokers, containerization — Docker, Kubernetes). - **Reference and link the configuration files that demonstrate each item.** --- ### 3. **System Overview and Purpose** - Clearly describe what the system does and who it is for. - What problems does it solve? - List the core functionalities. - If possible, relate the system to the business domains involved. - Provide a high-level description of the main features. --- ### 4. **Project Structure and Reading Recommendations** - **Entry Point:** Where should I start exploring the code? Identify the main entry points (e.g., `main.go`, `index.js`, `Program.cs`, `app.py`, `Application.java`). **Provide direct links to these files.** - **General Organization:** Explain the overall folder and file structure. Highlight important conventions. **Use real folder and file name examples.** - **Configuration:** Are there main configuration files? (e.g., `config.yaml`, `.env`, `appsettings.json`) Which configurations are critical? **Provide links.** - **Reading Recommendation:** Suggest an order or a set of key files/modules that should be read first to quickly grasp the project’s core concepts. --- ### 5. **Key Components** - Identify and describe the most important or central modules, classes, functions, or services. - Explain the responsibilities of each component. - Describe their responsibilities and interdependencies. - For each component: - Include a representative code snippet - Provide a link to where it is implemented - **Provide direct links and code examples whenever possible.** --- ### 6. **Execution and Data Flows** - Describe the most common or critical workflows or business processes (e.g., order processing, user authentication). - Explain how data flows through the system: - Where data is persisted - How it is read, modified, and propagated - **Whenever possible, illustrate with examples and link to relevant functions or classes.** #### 6.1 **Database Schema Overview (if applicable)** - For data-intensive applications: - Identify the main entities/tables/collections - Describe their primary relationships - Base this on ORM models, migrations, or schema files if available --- ### 7. **Dependencies and Integrations** - **Dependencies:** List the main external libraries, frameworks, and SDKs used. Briefly explain the role of each one. **Provide links to where they are configured or most commonly used.** - **Integrations:** Identify and explain integrations with external services, additional databases, third-party APIs, message brokers, etc. How does communication occur? **Point to the modules/classes responsible and include links.** #### 7.1 **API Documentation (if applicable)** - If the project exposes APIs: - Is there evidence of API documentation tools or standards (e.g., Swagger/OpenAPI, Javadoc, endpoint-specific docstrings)? - Where can this documentation be found or how can it be generated? --- ### 8. **Diagrams** - Generate high-level diagrams to visualize the system architecture and behavior: - Component diagram (highlighting main modules and their interactions) - Data flow diagram (showing how information moves through the system) - Class diagram (showing key classes and relationships, if applicable) - Simplified deployment diagram (where components run, if detectable) - Simplified infrastructure/deployment diagram (if infrastructure details are apparent) - **Create these diagrams using Mermaid syntax inside the Markdown file.** - Diagrams should be **high-level**; extensive detailing is not required. --- ### 9. **Testing** - Are there automated tests? - Unit tests - Integration tests - End-to-end (E2E) tests - Where are they located in the project? - Which testing framework(s) are used? - How are tests typically executed? - How can tests be run locally? - Is there any CI/CD strategy involving tests? --- ### 10. **Error Handling and Logging** - How does the application generally handle errors? - Is there a standard pattern (e.g., global middleware, custom exceptions)? - Which logging library is used? - Is there a standard logging format? - Is there visible integration with monitoring tools (e.g., Datadog, Sentry)? --- ### 11. **Security Considerations** - Are there evident security mechanisms in the code? - Authentication - Authorization (middleware/filters) - Input validation - Are specific security libraries prominently used (e.g., Spring Security, Passport.js, JWT libraries)? - Are there notable security practices? - Secrets management - Protection against common attacks --- ### 12. **Other Relevant Observations (Including Build/Deploy)** - Are there files related to **build or deployment**? - `Dockerfile` - `docker-compose.yml` - Build/deploy scripts - CI/CD configuration files (e.g., `.github/workflows/`, `.gitlab-ci.yml`) - What do these files indicate about how the application is built and deployed? - Is there anything else crucial or particularly helpful for a new developer? - Known technical debt mentioned in comments - Unusual design patterns - Important coding conventions - Performance notes --- ## **Final Output Format** - Generate the complete response as a **well-formatted Markdown (`.md`) document**. - Use **clear and direct language**. - Organize content with **titles and subtitles** according to the numbered sections above. - **Include relevant code snippets** (short and representative). - **Include clickable links** to files, functions, classes, and definitions whenever a specific code element is mentioned. - Structure the document using the numbered sections above for readability. **Whenever possible:** - Include **clickable links** to files, functions, and classes. - Show **short, representative code snippets**. - Use **bullet points or tables** for lists. --- ### **IMPORTANT** The analysis must consider **ALL files in the project**. Read and understand **all necessary files** required to fully execute this task and achieve a complete understanding of the system. --- ### **Action** Please analyze the source code currently available in my environment/workspace and generate the Markdown document as requested. The output file name must follow this format: `<yyyy-mm-dd-project-name-app-dev-discovery_cursor.md>`