Imported from ziyadsamhaoui/messaging-app (
AGENTS.md). Install upstream withnpx skills add ziyadsamhaoui/messaging-app. Copyright stays with the author.
Agent Guidelines for Messaging-application
This document provides essential knowledge for AI coding agents to be immediately productive in the Messaging-application codebase.
1. Big Picture Architecture
The application consists of a Java Spring Boot backend and a Next.js (App Router) frontend. They communicate via REST APIs and STOMP WebSockets.
- Frontend (
frontend/): Next.js, TailwindCSS, Motion library, STOMP over SockJS. - Backend (
src/main/java/messagerie/application/): Java Spring Boot.
Data Flow & Communication
- Authentication: REST
POST /api/auth/loginreturns a JWT token. This token is used for subsequent REST requests (Authorization: Bearer <token>) and for STOMP WebSocketCONNECTframes. - REST Endpoints:
- Conversations:
GET /api/conversations,POST /api/conversations - Messages:
GET /api/conversations/{id}/messages,POST /api/conversations/{id}/messages - Users:
GET /api/users/me,GET /api/users/{id},GET /api/users/username/{username}
- Conversations:
- WebSocket (STOMP):
- URL:
ws(s)://<host>/wsor/ws-sockjs - Subscriptions:
/topic/conversations: New conversation notifications./topic/conversations/{conversationId}: Messages for an open conversation./user/queue/errors: Per-user error notifications.
- Sending:
SEND /app/chat.sendwith payload{ "content": "..." }.
- URL:
- Pagination: Cursor-based using numeric IDs.
nextCursorindicates the last item ID in the returned page.nullmeans no more items. Smaller IDs are older messages.
2. Critical Developer Workflows
Frontend
- Requirements: Node.js 18+ (20+ recommended), Backend running.
- Environment: Create
frontend/.env.local:NEXT_PUBLIC_API_BASE_URL=http://localhost:8080 NEXT_PUBLIC_WS_URL=http://localhost:8000/ws - Run:
Access atnpm install npm run devhttp://localhost:3000. - Scripts:
npm run check:env: Quick environment validation.npm run lint: Linting.npm run build: Build for production.
Backend
- Build: The project uses Maven.
./mvnw clean install - Run:
./mvnw spring-boot:run - Docker:
compose.yamlis present for Docker Compose setup.
3. Project-Specific Conventions and Patterns
Frontend
- Design Philosophy: Avoid "AI slop" aesthetic. Focus on unique typography, cohesive botanical-inspired color themes, impactful motion (using Motion library), and atmospheric backgrounds.
- Color Palette: Two co-dominant anchors:
parchment(#E5D9B6) andforest(#285430), withfern(#5F8D4E) andsage(#A4BE7B) as midtone accents. Defined infrontend/styles/globals.cssandfrontend/tailwind.config.ts. - Styling: TailwindCSS is mandatory. CSS variables are used for consistency.
- Authentication: Tokens stored in React context/Zustand (not localStorage).
- Error Handling:
- Listen on
/user/queue/errorsforErrorResponseJSON. 401status: logout and redirect to/login.429status: respectRetry-Afterheader, implement exponential backoff.- Others: show toast with
ErrorResponse.message. - Global error boundary in Next.js.
- Listen on
- Component Architecture:
app/: Pages (/,/login,/app).components/ui: Reusable UI components (Button, Input, Avatar, etc.).components/chat: Chat-specific components (MessageBubble, MessageList, MessageInput).components/sidebar: Sidebar components (ConversationItem, NewConversationModal).lib/: API client, STOMP client, auth context.hooks/: Data and WebSocket hooks.
- Form Handling: Use React
useStatefor form state. No<form>tag; useonClickasync handlers. Disable inputs/buttons while loading. - Responsive Design: Mobile-first approach. Tailwind defaults for
sm,md,lgbreakpoints. - Image Optimization: Use
next/image. - Font Loading: Use
next/font.
4. Integration Points and External Dependencies
Frontend
- Dependencies:
@stomp/stompjs,sockjs-client,motion/react. - Backend Integration: Relies heavily on the Java Spring Boot backend for all data operations and real-time communication.
Backend
- Dependencies: Spring Boot, likely Spring Web, Spring Data, Spring Security, and WebSocket dependencies for STOMP.
- Database: Configuration likely in
src/main/resources/application.properties.
5. Key Files and Directories
frontend/: Next.js frontend application.frontend/app/: Next.js pages.frontend/components/: UI components.frontend/lib/: API, STOMP, Auth logic.frontend/hooks/: React hooks.frontend/styles/globals.css: Global CSS and color variables.frontend/tailwind.config.ts: Tailwind CSS configuration.frontend/.env.local: Local environment variables.
src/main/java/messagerie/application/: Java Spring Boot backend source code.src/main/java/messagerie/application/controller/: REST controllers.src/main/java/messagerie/application/service/: Business logic.src/main/java/messagerie/application/entity/: JPA entities.src/main/java/messagerie/application/config/: Spring configurations (e.g., WebSocket, Security).src/main/resources/application.properties: Backend configuration.
pom.xml: Maven project file for backend dependencies and build.compose.yaml: Docker Compose configuration.
