Full-Stack AI Agent Architecture

Meet ShopKart - a fictional Indian e-commerce store selling everything from running shoes to Bluetooth earbuds, all priced in rupees. A customer opens the storefront and types into a chat box:

> "I need wireless earbuds under 3000 rupees with good battery. Add the best one to my cart."

A normal search box cannot answer that. It has no idea what "good battery" means, cannot compare products, and certainly cannot add anything to a cart. But an AI agent can. It reads the request, searches the catalog through a tool, reasons about the results, checks stock, and places the order - all in one conversation.

Over the next eight lessons you will build exactly this system end to end: a Spring Boot REST API, a React storefront with a chat widget, and an AI agent wired in with Spring AI 1.0 that reasons and takes real actions. This first lesson gives you the map.

Chatbot vs Agent

The word "chatbot" gets thrown around a lot, so let us be precise. The difference is not the model - it is what the model is allowed to do.

A chatbot is a very smart autocomplete. An agent is a chatbot that has been handed a set of tools - Java methods bound to your real repositories - and the autonomy to decide when to call them. That single change is what turns "nice demo" into "does my job".

The full-stack picture

Everything in ShopKart flows through four layers. The browser never talks to the LLM directly - that would leak your API key and give the model no access to your data. Instead, the Spring Boot backend is the brain: it holds the key, owns the tools, and orchestrates the whole exchange.

Read that diagram left to right and it is the whole course:

• React browser renders the product grid and the ChatWidget. It sends user messages to the backend and streams replies back.
• Spring Boot API exposes REST endpoints, hosts the Spring AI ChatClient, defines the tools, and talks to the database.
• LLM provider (OpenAI by default; Anthropic Claude is a drop-in alternative in Spring AI) does the reasoning and decides which tools to call.
• Database and repositories hold the real ShopKart data the tools operate on.

The entities you will use everywhere

To keep things concrete, the same domain objects appear in every lesson. Here is the core Product in Java - memorise these fields, they show up in the API, the React grid, and the agent's tools.

public class Product {
    private Long id;
    private String name;
    private String category;     // "Footwear", "Audio", "Wearables"
    private String brand;        // "Nike", "boAt", "Noise"
    private BigDecimal price;    // in INR, e.g. 2499.00
    private double rating;       // 0.0 to 5.0
    private int stock;
    private String description;
    private List<String> tags;   // ["wireless", "bluetooth", "sports"]
}

Alongside Product you will build Customer and Order:

public class Order {
    private Long id;
    private Long customerId;
    private List<OrderItem> items;   // productId + quantity
    private BigDecimal total;        // computed in INR
    private String status;           // "PLACED", "SHIPPED", "DELIVERED"
}

Using BigDecimal for money is deliberate. Rupee amounts must be exact - double arithmetic will happily tell you that a 999 rupee item plus an 899 rupee item costs 1897.9999999 rupees, and that is the kind of bug that reaches production.

How one request actually flows

When the customer asks for earbuds under 3000 rupees, here is the sequence. Notice that a single user message can trigger several round-trips between Spring Boot and the LLM before the customer sees a reply.

• ChatWidget POSTs the message to POST /api/chat.
• The ChatClient sends the conversation plus the list of available tools to the LLM.
• The LLM replies "call searchProducts(query='wireless earbuds', maxPrice=3000)".
• Spring AI executes that Java method against your ProductRepository and feeds the JSON result back to the LLM.
• The LLM reasons over the products, maybe calls checkStock, then writes a natural-language answer.
• Spring Boot streams that answer back to the browser token by token.

You will build each of these pieces in order. By lesson 5 the loop in steps 2 to 5 runs on its own - that is the agent.

Project setup overview

You are really building two applications that live in one repository:

shopkart/
  backend/                 # Spring Boot 3.x, Java 17+
    pom.xml                # spring-boot-starter-web, spring-ai-*
    src/main/java/com/shopkart/
      Product.java, Order.java, Customer.java
      ProductController.java, OrderController.java, ChatController.java
      ProductRepository.java
      ShopKartTools.java    # @Tool methods (added in lesson 5)
    src/main/resources/
      application.properties
  frontend/                # React 18 + Vite
    src/
      App.jsx
      ProductGrid.jsx
      ChatWidget.jsx

The backend needs Java 17 or newer and Spring Boot 3.x, because Spring AI 1.0 requires them. The frontend is a standard Vite + React 18 app. During development the React dev server runs on port 5173 and Spring Boot on 8080, so you will enable CORS on the backend - we will handle that in lesson 3.

Key takeaways

• ShopKart is one running project - a Spring Boot API, a React storefront, and an AI agent - built end to end across the course.
• A chatbot only generates text; an agent is given tools and can reason, act, and observe in a loop.
• The Spring Boot backend is the brain: it holds the LLM API key, owns the tools, and talks to the database. The browser only ever calls your API.
• The shared entities - Product, Customer, Order - appear in the API, the React UI, and the agent's tools. Use BigDecimal for rupee amounts.
• You will assemble the system in order: REST API, React UI, LLM wiring, tool-calling agent, MCP, and streaming.

Next up: The Spring Boot E-Commerce API - where you build the ShopKart REST endpoints and seed data that everything else depends on.