# AI-Native CRM: Agent Handoff Guide

> [!IMPORTANT]
> This document is for the AI Agent to quickly understand the project context, architecture, and current status during session resume.

## 🎯 Project Vision
An **AI-Native CRM** where business modules and data are managed through AI-driven messages and tools, rather than traditional REST parameters.

---

## 🏗️ Architecture Overview

### Backend (`/backend`)
*   **Env**: JDK 19 + Spring Boot 3.2.4 + PostgreSQL.
*   **Key Logic**:
    *   `CrmTools.java`: **The Message Hub**. Contains `@Tool` methods for **Define, Save, and Delete**. Directly interacts with Repositories.
    *   `AgentController.java`: **Primary Entry Point**. Handles natural language commands or "Business Fact Reports".
    *   **AI-Only Policy**: Create/Update/Delete endpoints have been removed from traditional controllers to force AI-driven flows.

### Frontend (`/frontend`)
*   **Env**: Next.js 15 (App Router).
*   **Components**:
    *   `DynamicForm.tsx`: Shared component supporting **Entity Associations (`x-link-entity`)**, Enums, and Format constraints.
    *   `EntityDataPage` (`/data/[entityCode]`): Full CRUD UI. Actions (Edit/Delete) route through AI messages.

---

## 🛠️ Key File Responsibilities

| File | Role |
| :--- | :--- |
| `backend/.../CrmTools.java` | **Source of Truth** for all data-changing tools. |
| `frontend/src/components/DynamicForm.tsx` | Reusable Form Renderer (Schema + AI messaging). |
| `frontend/src/app/data/[entityCode]/page.tsx` | Dynamic List View with Agent-driven Actions. |

---

## 🔄 Core Conventions

1.  **AI-First Mutation**: DO NOT create manual REST services for data mutation. Use the AI Tool interface.
2.  **Schema Extensions**:
    *   Associations: `x-link-entity: 'module_code'`.
    *   Constraints: `enum`, `pattern`, `format: 'date'`.
3.  **Fact-Based Messaging**: Frontend should report business facts (e.g., "User filled form X") and let the AI decide the tool to call.

---

## 🚀 Current Progress & Next Steps
- [x] AI-Native CRUD implemented (Agent-driven Insert/Update/Delete).
- [x] Entity Associations & Selectors supported.
- [x] Unified DynamicForm for Generation & Management.
- [ ] Next: Implement Advanced Search & Filtering via AI Query generation.
- [ ] Next: Dashboard Analytics module for dynamic data summary.

---
*Updated at: 2026-03-25. Follow this guide for AI-Native CRM development.*