updated README

Author: rhofkens

README.md

@@ -1,8 +1,36 @@
-# Auth‑vs‑Guest Demo Web App
+# AI-Developed OIDC Auth Demo (React + Spring Boot)
 
-A minimal web application that visually demonstrates the difference between guest and authenticated access to backend services.
+[![CI](https://github.com/rhofkens/oidc-auth-react-springboot-demo/actions/workflows/ci.yml/badge.svg)](https://github.com/rhofkens/oidc-auth-react-springboot-demo/actions/workflows/ci.yml)
 
-[![CI](https://github.com/[your-username]/oidc-auth-react-springboot-demo/actions/workflows/ci.yml/badge.svg)](https://github.com/[your-username]/oidc-auth-react-springboot-demo/actions/workflows/ci.yml)
+## What This Project Does
+
+This project is a minimal web application designed to visually demonstrate the difference between guest and authenticated user access to backend services using OpenID Connect (OIDC). It serves as a practical example and base implementation for integrating standard OIDC authentication flows in a modern web stack.
+
+**Key Features:**
+
+*   **Guest vs. Authenticated Views:** Clearly shows different UI states and data access based on whether the user is logged in or browsing as a guest.
+*   **OIDC Integration:** Implements standard OIDC Authorization Code flow with PKCE for secure authentication against an OIDC provider (configured for Zitadel).
+*   **Frontend-Backend Interaction:** Features a React frontend that interacts with a Spring Boot backend API.
+*   **Protected Resources:** Includes a public API endpoint accessible to everyone and a private endpoint requiring authentication.
+*   **Session Management:** Demonstrates handling of authentication tokens and session persistence across browser refreshes.
+
+**Technology Stack:**
+
+*   **Backend:** Java 21, Spring Boot 3.4.4, Spring Security 6 (Resource Server), Maven
+*   **Frontend:** React 19, TypeScript, Vite, Tailwind CSS, shadcn/ui, oidc-client-ts
+*   **Authentication:** OIDC (Authorization Code + PKCE), JWT validation
+
+## Why and How This Project Was Developed
+
+This project was developed with a specific goal: **to create an enterprise-grade, reusable authentication package using a fully automated AI-native coding workflow.**
+
+*   **Goal:** The primary objective was to build a robust foundation for OIDC authentication that adheres to modern best practices, achieves high test coverage (≥80%), includes comprehensive documentation, and can be readily adapted for real-world enterprise projects. A secondary goal was to establish and refine a clear, repeatable workflow for AI-driven software development using VScode and Roo Code.
+*   **Process:**
+    *   The initial Product Requirements Document (PRD), Architecture Guidelines, Coding Guidelines, and High-Level Plan were drafted using an AI assistant (o3).
+    *   From that point, the entire implementation followed a strictly automated flow defined in `.clinerules` and `.roomodes`, executed by Roo Code.
+    *   While highly automated, the workflow incorporated deliberate human review checkpoints at key stages (e.g., after planning subtasks for each implementation step). This ensured alignment and allowed for course correction where needed, keeping the human developer in control.
+*   **AI Models Used:** The core coding tasks were performed by Large Language Models, specifically Anthropic's Sonnet 3.7 and Google's Gemini Pro (preview-03-25). While both were effective, the code generated by Gemini Pro was often preferred, though it came at a higher operational cost.
+*   **Outcome:** The development process achieved a high degree of automation (estimated at 97%+), successfully producing the target application according to the predefined specifications and quality gates. It validated the AI-native workflow as a viable approach for building quality software components efficiently.
 
 ## Prerequisites
 
@@ -16,13 +44,15 @@ This is a monorepo containing:
 
 - `backend/`: Spring Boot 3.4.4 application (Java 21)
 - `frontend/`: React 19 application with TypeScript, Vite, and Tailwind CSS
+- `docs/`: Project documentation, including PRD, architecture, guidelines, and implementation plans.
 
 ## Getting Started
 
 ### Backend
 
 ```bash
 cd backend
+# Ensure .env file is configured (see Environment Variables section)
 ./mvnw spring-boot:run
 ```
 
@@ -33,6 +63,7 @@ The backend will start on http://localhost:8080.
 ```bash
 cd frontend
 pnpm install
+# Ensure .env file is configured (see Environment Variables section)
 pnpm dev
 ```
 
@@ -50,7 +81,7 @@ The frontend implements a caching mechanism for the public health check endpoint
 
 ## Environment Variables
 
-This project uses environment variables for configuration, particularly for OIDC authentication details needed from Step 7 onwards. Template files are provided:
+This project uses environment variables for configuration, particularly for OIDC authentication details. Template files are provided:
 
 - `.env.example` (at the project root, for backend configuration)
 - `frontend/.env.example` (in the frontend directory, for frontend configuration)
@@ -77,7 +108,7 @@ To run the application with OIDC authentication enabled, you need to configure t
 
 - `VITE_ZITADEL_ISSUER_URI`: The URI of your Zitadel instance.
 - `VITE_ZITADEL_CLIENT_ID`: The Client ID of your Zitadel application.
-- `VITE_ZITADEL_SCOPES`: The OIDC scopes required by the application (e.g., `openid profile email`).
+- `VITE_ZITADEL_SCOPES`: The OIDC scopes required by the application (e.g., `openid profile email private.read`).
 
 Additionally, ensure your Zitadel client application is configured with the following settings:
 
@@ -144,11 +175,11 @@ The coverage thresholds are configured to require at least 80% coverage for stat
 
 - The backend uses Spotless for code formatting. Run `./mvnw spotless:apply` to format the code.
 - The frontend uses ESLint and Prettier for linting and formatting. Run `pnpm lint` and `pnpm format` to lint and format the code.
-- Pre-commit hooks are set up to ensure code quality before commits.
+- Pre-commit hooks are set up using `lint-staged` and `husky` to ensure code quality before commits.
 
 ## API Endpoints
 
-### Health Check
+### Health Check (Public)
 
 ```bash
 curl -X GET http://localhost:8080/api/v1/public/health
@@ -160,20 +191,19 @@ Example response:
   "message": "Service up"
 }
 
-### Testing Private Endpoint
-
-To test the private endpoint, you need a valid JWT access token obtained from your OIDC provider (e.g., Zitadel). This token must contain the necessary claims or roles (like `AUTH_USER`) that the backend expects.
+### Private Info (Requires Authentication)
 
 ```bash
-# Replace <your_jwt_token> with a valid access token
+# Replace <your_jwt_token> with a valid access token obtained via OIDC login
 curl -H "Authorization: Bearer <your_jwt_token>" http://localhost:8080/api/v1/private/info
 ```
 
 Example response (if authorized):
 ```json
 {
-  "info": "This is private information for authenticated users."
+  "info": "This is private information for authenticated users.",
+  "email": "user@example.com" 
 }
 ```
 
-You can obtain a test token from the Zitadel console or by using an OIDC client tool after authenticating.
+You can obtain a test token by logging into the frontend application, which stores the access token. You can inspect network requests or use browser developer tools to find the token.