Document CI and container setup

Author: albonidrizi

.env.example

@@ -0,0 +1,21 @@
+POSTGRES_DB=nexusdb
+POSTGRES_USER=nexus
+POSTGRES_PASSWORD=nexus_dev_password
+POSTGRES_PORT=5432
+
+RABBITMQ_USERNAME=nexus
+RABBITMQ_PASSWORD=nexus_dev_password
+RABBITMQ_PORT=5672
+RABBITMQ_MANAGEMENT_PORT=15672
+
+BACKEND_PORT=8080
+FRONTEND_PORT=5173
+VITE_API_URL=http://localhost:8080/api
+APP_CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000
+APP_OUTBOX_ENABLED=true
+APP_OUTBOX_PUBLISH_DELAY_MS=5000
+APP_OUTBOX_BATCH_SIZE=25
+APP_OUTBOX_MAX_ATTEMPTS=8
+
+JWT_SECRET=replace-with-at-least-32-characters-for-local-dev
+SEED_ENABLED=true

.github/workflows/ci.yml

@@ -27,6 +27,10 @@ jobs:
 
       - name: Build and test
         working-directory: server
+        env:
+          JWT_SECRET: ci-test-secret-key-must-be-at-least-32-characters
+          SPRING_DATASOURCE_PASSWORD: ci-postgres-password
+          SPRING_RABBITMQ_PASSWORD: ci-rabbitmq-password
         run: mvn -B verify
 
   frontend:
@@ -39,7 +43,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '22'
           cache: 'npm'
           cache-dependency-path: client/package-lock.json
 
@@ -50,3 +54,7 @@ jobs:
       - name: Build
         working-directory: client
         run: npm run build
+
+      - name: Lint
+        working-directory: client
+        run: npm run lint

README.md

@@ -1,153 +1,188 @@
-# NexusFlow: Enterprise Order Processor
+# NexusFlow Enterprise Order Processor
 
-NexusFlow is a **senior-level enterprise order processing platform** engineered for high concurrency, scalability, and data integrity. It orchestrates a secure Spring Boot backend with a responsive React frontend, utilizing event-driven architecture to handle complex workflows efficiently.
+NexusFlow is a Spring Boot + React order-processing system that demonstrates enterprise backend design, secure role-based workflows, PostgreSQL persistence, and RabbitMQ-driven async order handling.
 
-## 🌟 Key Features
+## Problem It Solves
 
-### 1. Robust Data Integrity (Optimistic Locking)
-- **Problem**: In high-concurrency environments, multiple users might attempt to purchase the last item simultaneously ("The Lost Update" problem).
-- **Solution**: Implemented JPA `@Version` based optimistic locking on `Product` entities.
-- **Outcome**: Ensures strict ACID compliance. If concurrent transactions conflict, the system detects the version mismatch and handles the `ObjectOptimisticLockingFailureException` gracefully, preventing negative stock and ensuring data consistency.
+Enterprise order systems need to validate inventory, reserve stock, process payments, expose operational order workflows, and keep an audit trail without letting controllers become business-logic dumping grounds. NexusFlow models that flow in a compact portfolio project that is realistic enough for senior Java/Spring interviews without pretending to be a full ERP.
 
-### 2. Event-Driven Architecture (RabbitMQ)
-- **Decoupling**: Order placement is decoupled from heavy post-processing tasks (inventory sync, notifications, analytics).
-- **Resilience**: Uses **RabbitMQ** to buffer events. If downstream services fail, messages persist in the `order_placed_queue` for retry, ensuring zero data loss.
-- **Performance**: shifting heavy lifting to async workers reduces the Order API response time to ~100ms, compared to seconds in synchronous systems.
+## Tech Stack
 
-### 3. Enterprise-Grade Security
-- **Stateless Authentication**: Secured via **Spring Security** and **JWT (JSON Web Tokens)**.
-- **Role-Based Access Control (RBAC)**: Fine-grained permissions for `User` and `Admin` roles protecting sensitive endpoints.
+- Backend: Java 17, Spring Boot 3.2, Spring Web, Spring Data JPA, Spring Security, JWT, Spring AMQP, Actuator, OpenAPI
+- Frontend: React 19, TypeScript, Vite, React Router, Axios, vanilla CSS
+- Data and infrastructure: PostgreSQL 15, Flyway, RabbitMQ Management, Docker Compose
+- Testing: JUnit 5, Mockito, Spring MVC tests, Spring Data JPA tests, Testcontainers for PostgreSQL when Docker is available
+- CI: GitHub Actions for backend verification, frontend build, and frontend lint
 
-### 4. Comprehensive Input Validation
-- **Bean Validation**: All DTOs validated with `@Valid`, `@NotNull`, `@Min`, `@Max`, `@NotBlank` annotations.
-- **Detailed Error Messages**: User-friendly validation error responses with field-specific messages.
+## Architecture
 
-### 5. Advanced Exception Handling
-- **Custom Exceptions**: `ResourceNotFoundException`, `InsufficientStockException` for business logic errors.
-- **Optimistic Locking Handler**: Graceful handling of concurrent modification conflicts.
-- **Structured Error Responses**: Consistent error format with timestamp, status, message, and validation errors.
+The backend uses a pragmatic package structure:
 
-### 6. API Documentation (Swagger/OpenAPI)
-- **Interactive API Explorer**: Full REST API documentation with try-it-out functionality.
-- **JWT Integration**: Built-in authentication support in Swagger UI.
+- `domain/model`: JPA entities and enums
+- `application/service`: business rules, state machine, metrics
+- `infrastructure/persistence`: Spring Data repositories
+- `infrastructure/messaging`: transactional outbox, RabbitMQ configuration, message DTOs, publisher, consumer
+- `web/controller` and `web/dto`: REST API and DTO boundaries
+- `security`, `config`, `exception`: JWT/RBAC, CORS, request correlation, health, structured errors
 
-### 7. Observability & Monitoring
-- **Spring Actuator**: Health checks, metrics, and application monitoring endpoints.
-- **Structured Logging**: SLF4J with contextual logging across all services.
-
-## 🏗 System Architecture
-
-The system follows a microservices-inspired architecture managed via Docker Compose:
+```mermaid
+flowchart LR
+  User[React UI] --> API[Spring Boot REST API]
+  API --> Auth[JWT + RBAC]
+  API --> Service[Order Application Service]
+  Service --> DB[(PostgreSQL + Flyway)]
+  Service --> Outbox[Transactional Outbox]
+  Outbox --> DB
+  Outbox --> MQ[RabbitMQ Topic Exchange]
+  MQ --> Worker[Async Order Worker]
+  Worker --> Service
+  API --> Actuator[Actuator + Metrics]
+```
 
-1.  **Frontend**: React (Vite) + TypeScript for a type-safe, performant UI.
-2.  **Backend**: Spring Boot 3.2 REST API.
-3.  **Database**: PostgreSQL 15 (Relational/ACID).
-4.  **Message Broker**: RabbitMQ (Async messaging).
+## Order Lifecycle
 
-### Architecture Diagram
 ```mermaid
-graph TD
-    Client[React Client] -->|REST API| Server[Spring Boot Server]
-    Server -->|Read/Write| DB[(PostgreSQL)]
-    Server -->|Publish Event| MQ[RabbitMQ]
-    MQ -->|Consume Event| Listener["Async Worker (Internal)"]
+stateDiagram-v2
+  [*] --> CREATED
+  CREATED --> VALIDATED: stock reserved
+  VALIDATED --> PAID: payment captured
+  PAID --> PROCESSING: async worker
+  PROCESSING --> SHIPPED: async worker or manager
+  SHIPPED --> DELIVERED: manager
+  CREATED --> CANCELLED
+  VALIDATED --> CANCELLED
+  PAID --> CANCELLED
+  CREATED --> FAILED
+  VALIDATED --> FAILED
+  PAID --> FAILED
+  PROCESSING --> FAILED
 ```
 
-## 🛠 Tech Stack
+## Key Features
 
-### Backend
-- **Framework**: Spring Boot 3.2
-- **Language**: Java 17
-- **Data**: Spring Data JPA, PostgreSQL
-- **Security**: Spring Security, JWT (io.jsonwebtoken)
-- **Messaging**: Spring AMQP (RabbitMQ)
-- **Tools**: Lombok, Maven
+- Validated order creation with stock reservation and idempotency key support
+- Payment simulation that commits or releases reserved inventory
+- Enforced order status transitions with clear `409 Conflict` responses
+- Order audit history for lifecycle changes with actor and correlation ID
+- Paged, filterable, sortable order listing
+- Flyway-managed database schema
+- Transactional outbox for RabbitMQ status-change events
+- RabbitMQ durable queue and dead-letter queue
+- Async worker that advances paid orders into processing and shipped states
+- JWT authentication with `USER`, `MANAGER`, and `ADMIN` roles
+- BCrypt password hashing and seeded demo users
+- DTO-based REST API responses instead of leaking JPA entity graphs
+- Structured error responses with validation details and correlation IDs
+- Actuator health and order-processing health indicator
+- React dashboard for order creation, payment, cancellation, and history
+- Operations UI for inventory visibility and staff order transitions
 
-### Frontend
-- **Framework**: React 19
-- **Build Tool**: Vite 7
-- **Language**: TypeScript 5
-- **Routing**: React Router DOM 7
-- **HTTP Client**: Axios
-- **Styling**: Vanilla CSS (Modular & Responsive)
+## Security
 
-## 🚀 Getting Started
+- Public endpoints: `/api/auth/register`, `/api/auth/login`, Swagger, API docs, health
+- Authenticated endpoints: product list, order creation/list/detail/payment/status
+- Staff endpoints: inventory and operational order actions
+- Admin-only endpoints: create/update/delete products
+- Sensitive values are read from environment variables; see `.env.example`
+- Public registration creates `ROLE_USER` only; staff users are seeded for local demo
 
-### Quickstart (Docker Compose)
-- `docker-compose up --build`
-- Frontend: http://localhost:5173
-- API: http://localhost:8080
-- Swagger: http://localhost:8080/swagger-ui.html (use the token field to authorize)
-- Health/Metrics: http://localhost:8080/actuator/health, http://localhost:8080/actuator/metrics
-- RabbitMQ UI: http://localhost:15672 (guest/guest)
+## Async Processing
+
+When an order reaches `PAID`, the order transaction stores an `ORDER_STATUS_CHANGED` message in `outbox_events` with a correlation ID. A scheduled relay publishes pending outbox rows to the `nexusflow.orders` topic exchange and marks them `PUBLISHED`, `FAILED`, or `DEAD` based on retry outcome. The RabbitMQ consumer listens on `nexusflow.order-events` and advances paid orders to `PROCESSING` and then `SHIPPED`. Failed RabbitMQ deliveries route to `nexusflow.order-events.dlq`.
 
-### Prerequisites
-- [Docker Desktop](https://www.docker.com/products/docker-desktop/) (Required)
-- Java 17+ & Node.js 18+ (Optional, for local non-Docker dev)
+## Run Locally
 
-### Deployment (Recommended)
-Run the entire stack with a single command:
+Prerequisites: Docker Desktop.
 
 ```bash
-docker-compose up --build
+docker compose --env-file .env.example up --build
 ```
 
-**Access Points**:
-- **Frontend**: [http://localhost:5173](http://localhost:5173)
-- **Backend API**: [http://localhost:8080](http://localhost:8080)
-- **Swagger UI**: [http://localhost:8080/swagger-ui.html](http://localhost:8080/swagger-ui.html)
-- **API Docs**: [http://localhost:8080/api-docs](http://localhost:8080/api-docs)
-- **Health Check**: [http://localhost:8080/actuator/health](http://localhost:8080/actuator/health)
-- **Metrics**: [http://localhost:8080/actuator/metrics](http://localhost:8080/actuator/metrics)
-- **RabbitMQ Dashboard**: [http://localhost:15672](http://localhost:15672) (User: `guest`, Pass: `guest`)
-
-### Local Development (Optional)
-- Backend: `cd server && mvn spring-boot:run`
-- Frontend: `cd client && npm install && npm run dev`
-- Tests: `cd server && mvn test`
-- Frontend build check: `cd client && npm run build`
-- Health check: `curl http://localhost:8080/actuator/health`
-
-### Auth & Roles
-- Register or login at `/api/auth/register` or `/api/auth/login` (Swagger is the fastest way to try it).
-- In Swagger, paste the JWT in **Authorize** without the `Bearer` prefix.
-- Default role: `ROLE_CUSTOMER`; promote to admin manually or use the seeded admin credentials below.
-
-### Dev seed (auto)
-- Default admin (dev/demo): `admin` / `admin123` (seed is enabled when `SEED_ENABLED=true`, default).
-- Sample products are auto-created when the DB is empty.
-
-### Promote to Admin (quick SQL)
-```sql
-update users set role = 'ROLE_ADMIN' where username = 'your_username';
+Access points:
+
+- Frontend: http://localhost:5173
+- Backend API: http://localhost:8080
+- Swagger UI: http://localhost:8080/swagger-ui.html
+- API docs: http://localhost:8080/api-docs
+- Health: http://localhost:8080/actuator/health
+- RabbitMQ dashboard: http://localhost:15672
+
+Demo credentials from seed data:
+
+- User: `user` / `user12345`
+- Manager: `manager` / `manager123`
+- Admin: `admin` / `admin123`
+- RabbitMQ UI: values from `.env.example` (`nexus` / `nexus_dev_password`)
+
+For local non-Docker backend work, set `JWT_SECRET`, `SPRING_DATASOURCE_PASSWORD`, and `SPRING_RABBITMQ_PASSWORD` before running `mvn spring-boot:run`.
+
+## API Highlights
+
+- `POST /api/orders` with `Idempotency-Key`
+- `GET /api/orders?status=VALIDATED&size=10&sort=createdAt,desc`
+- `GET /api/orders/{id}`
+- `POST /api/orders/{id}/payments`
+- `PATCH /api/orders/{id}/status`
+- `GET /api/products`
+- `GET /api/admin/inventory`
+- `POST /api/admin/products`
+
+## Testing
+
+```bash
+cd server
+mvn test
+
+cd ../client
+npm ci
+npm run lint
+npm run build
 ```
 
-### CI (GitHub Actions)
-- Workflow: `.github/workflows/ci.yml`
-- Backend: `mvn verify` in `server`
-- Frontend: `npm ci && npm run build` in `client`
+Current automated coverage includes:
+
+- Order state transitions, idempotency, stock reservation, payment commit/release
+- Transactional outbox enqueueing and relay publish/retry behavior
+- Product service validation paths
+- Controller validation, authentication requirement, payment/status endpoints
+- JPA optimistic locking
+- PostgreSQL Testcontainers persistence check when Docker is available
+
+On the current machine, the Testcontainers test skipped because Docker Desktop was not exposing a usable Docker engine. The rest of the backend suite passed.
+
+## CI/CD
+
+`.github/workflows/ci.yml` runs:
+
+- Backend: `mvn -B verify`
+- Frontend: `npm ci`, `npm run build`, `npm run lint`
+
+No README badges are included because badges should only be added after the workflow runs successfully on the repository remote.
+
+## Screenshots
 
-> **Note:** Use JDK 17 for local Maven builds. Using newer JDKs (e.g., 21/23) can trigger `TypeTag :: UNKNOWN` javac errors with Lombok; Docker Compose already uses the correct JDK.
+Screenshots are not committed yet. Recommended captures after starting Docker Compose:
 
-### API Documentation (Swagger)
-1) Start services, then open [http://localhost:8080/swagger-ui.html](http://localhost:8080/swagger-ui.html)
-2) Click **Authorize** and paste your JWT (no `Bearer ` prefix needed)
-3) Try any endpoint directly from the UI
+- Login page with demo credential note
+- User dashboard showing product availability and order history
+- Operations page showing inventory reservations and order transitions
+- Swagger UI with authorized JWT
+- RabbitMQ queue view for `nexusflow.order-events`
 
-### Validation & Errors
-- All request DTOs are validated (`@Valid`, `@NotNull`, `@Min`, `@NotBlank`)
-- Errors return a structured payload: `timestamp`, `status`, `error`, `message`, `path`, and `validationErrors`
-- Concurrency conflicts return HTTP 409 with guidance to retry
+## Interview Talking Points
 
-### Monitoring
-- Health: `/actuator/health`
-- Metrics: `/actuator/metrics`
-- Prometheus scrape: `/actuator/prometheus`
+- Why order transitions belong in an application service/state machine instead of controllers
+- How optimistic locking protects stock updates under concurrent orders
+- Why stock is reserved at validation and committed at payment capture
+- How idempotency protects retries from duplicate order creation
+- How the transactional outbox prevents order commits from depending on RabbitMQ availability
+- How RBAC is split between endpoint security and business rules
+- How structured errors and correlation IDs improve debugging
 
-### Default Roles
-- **User**: Register a new account via the UI.
-- **Admin**: Manually update the database `users` table to promote a user to `ROLE_ADMIN` to access inventory management features.
+## What I Would Improve Next
 
-## 🧪 Future Improvements
-- **Integration Testing**: Add Testcontainers to simulate real PostgreSQL/RabbitMQ instances during CI/CD.
-- **Observability**: Integrate Prometheus and Grafana for metrics monitoring.
+- Add RabbitMQ Testcontainers coverage
+- Add a replay/admin endpoint for dead outbox events
+- Add refresh tokens and token revocation for a production auth model
+- Add Playwright UI tests and committed screenshots
+- Add Prometheus/Grafana dashboards for the custom order metrics