Docs: Add Happy Path guide for crAPI. (#360)

* docs: add -L flag to curl commands to follow redirects

* docs: add happy path guide and link from README

---------

Co-authored-by: Roshan Piyush <piyush.roshan@gmail.com>

Author: siddharthkarn2212

README.md

@@ -10,6 +10,15 @@ know more about crAPI, please check [crAPI's overview][overview].
 
 ## QuickStart Guide
 
+### Application Workflow (Happy Path)
+
+After setting up crAPI, it is recommended to follow the intended user workflow
+to understand how the application is supposed to work before attempting any
+security challenges.
+
+-[Application Workflow (Happy Path)](docs/happy-path.md)
+
+
 ### Docker and docker compose
 
 You'll need to have Docker and docker compose installed and running on your host system. Also, the version of docker compose should be `1.27.0` or above. Check your docker compose version using:

docs/happy-path.md

@@ -0,0 +1,124 @@
+# crAPI – Happy Path Guide
+
+## Purpose of This Document
+crAPI (Completely Ridiculous API) is intentionally vulnerable, but new users often struggle to understand
+how the application is supposed to work *before* exploring security issues.
+
+This document explains the **happy path** — the normal, intended workflow — so users can:
+- Understand application behavior
+- Navigate APIs with confidence
+- Clearly differentiate expected behavior vs vulnerabilities
+
+---
+
+## Prerequisites
+Before following this guide, ensure:
+- crAPI is running locally using Docker
+- You can access:
+  - Swagger UI (OpenAPI)
+  - Postman collection (optional but recommended)
+
+---
+
+## Application Overview (Conceptual)
+crAPI simulates a backend system for:
+- User identity and authentication
+- User profiles
+- Mechanic services
+- Orders and notifications
+
+The happy path represents **how a legitimate user interacts with the system**.
+
+---
+
+## Happy Path Workflow (High Level)
+
+1. User signs up
+2. User logs in
+3. User accesses their profile
+4. User interacts with available APIs as intended
+5. System responds with valid data and permissions
+
+---
+
+## Step-by-Step Happy Path
+
+### 1. User Registration
+**Goal:** Create a new user account
+
+- Endpoint: `/identity/api/auth/signup`
+- Action:
+  - Provide email, username, and password
+- Expected Result:
+  - Successful registration confirmation
+
+This step establishes a valid user identity in the system.
+
+---
+
+### 2. User Login
+**Goal:** Authenticate and obtain an access token
+
+- Example endpoint: `/identity/api/auth/signup`
+- Action:
+  - Login using registered credentials
+- Expected Result:
+  - Access token returned
+
+This token is required for all authenticated API calls.
+
+---
+
+### 3. Access User Profile
+**Goal:** Verify authenticated access
+
+- Example endpoint: `/identity/api/auth/signup`
+- Action:
+  - Include access token in Authorization header
+- Expected Result:
+  - User’s own profile data is returned
+
+This confirms authentication and authorization are working as intended.
+
+---
+
+### 4. Explore Available APIs
+**Goal:** Understand normal system behavior
+
+- Browse Swagger UI to view:
+  - User APIs
+  - Mechanic APIs
+  - Order-related APIs
+- Execute read-only or permitted actions
+
+This step helps users recognize **expected responses** and permissions.
+
+---
+
+### 5. Normal Application Usage
+**Goal:** Follow intended business logic
+
+- Create or view resources where permitted
+- Receive appropriate success or error responses
+- Observe correct access controls
+
+At this stage, users fully understand the baseline system behavior.
+
+---
+
+## Why This Matters
+Understanding the happy path allows users to:
+- Identify where behavior deviates from expectations
+- Recognize insecure authorization or validation
+- Learn API security concepts more effectively
+
+This guide should be followed **before attempting any challenges or exploitation**.
+
+---
+
+## Next Steps
+Once the happy path is clear, users can proceed to:
+- `docs/challenges.md`
+- `docs/challengeSolutions.md`
+
+to explore vulnerabilities intentionally built into crAPI.