Adds reverse engineering docs and adds new aidlc feature for front-end development

aidlc-docs/_shared/reverse-engineering/api-documentation.md

@@ -0,0 +1,125 @@
+# API Documentation
+
+## REST APIs
+
+### Authentication
+
+#### POST /auth/login
+- **Method**: POST
+- **Path**: `/auth/login`
+- **Purpose**: Authenticate a user and receive JWT tokens
+- **Authorization**: Anonymous
+- **Request**: `{ "email": string, "password": string }`
+- **Response**: `{ "accessToken": string, "refreshToken": string, "expiresAt": datetime, "user": { "id": guid, "email": string, "naam": string, "role": string } }`
+
+#### POST /auth/refresh
+- **Method**: POST
+- **Path**: `/auth/refresh`
+- **Purpose**: Refresh an access token using a valid refresh token
+- **Authorization**: Anonymous
+- **Request**: `{ "accessToken": string, "refreshToken": string }`
+- **Response**: Same as `/auth/login`
+
+#### POST /auth/revoke
+- **Method**: POST
+- **Path**: `/auth/revoke`
+- **Purpose**: Revoke a refresh token (logout)
+- **Authorization**: Bearer JWT required
+- **Request**: `"<refreshToken>"` (string body)
+- **Response**: 204 No Content
+
+---
+
+### Setup
+
+#### GET /setup/status
+- **Method**: GET
+- **Path**: `/setup/status`
+- **Purpose**: Check if the system has been initialized (first owner created)
+- **Authorization**: Anonymous
+- **Response**: `{ "initialized": boolean }`
+
+#### POST /setup/owner
+- **Method**: POST
+- **Path**: `/setup/owner`
+- **Purpose**: Create the initial Owner account (only usable when system is not yet initialized)
+- **Authorization**: Anonymous
+- **Request**: `{ "email": string, "password": string }`
+- **Response**: `{ "message": string }`
+
+---
+
+### Users
+
+#### POST /users/invite
+- **Method**: POST
+- **Path**: `/users/invite`
+- **Purpose**: Invite a new user by email with a specified role
+- **Authorization**: Bearer JWT, Policy: AdminOnly
+- **Request**: `{ "email": string, "role": string }`
+- **Response**: `{ "inviteLink": string }`
+
+#### POST /users/complete-setup
+- **Method**: POST
+- **Path**: `/users/complete-setup`
+- **Purpose**: Complete account setup using an invitation token
+- **Authorization**: Anonymous
+- **Request**: `{ "token": string, "password": string }`
+- **Response**: `{ "message": string }`
+
+#### GET /users/validate-invitation
+- **Method**: GET
+- **Path**: `/users/validate-invitation?token={token}`
+- **Purpose**: Validate an invitation token before showing the setup form
+- **Authorization**: Anonymous
+- **Response**: `{ "valid": boolean, "email": string, "role": string }` or error
+
+---
+
+### Availability
+
+#### GET /availability/status
+- **Method**: GET
+- **Path**: `/availability/status`
+- **Purpose**: Get current system availability status
+- **Authorization**: Anonymous
+- **Response**: `{ "status": "Available|Maintenance|Unavailable", "checkedAt": datetime, "message": string }`
+
+#### POST /availability/admin/status
+- **Method**: POST
+- **Path**: `/availability/admin/status`
+- **Purpose**: Update the system availability status
+- **Authorization**: Bearer JWT, Policy: OwnerOnly
+- **Request**: `{ "newStatus": "Available|Maintenance|Unavailable", "reason": string }`
+- **Response**: 200 OK or 400 Bad Request
+
+---
+
+## Authorization Policies
+
+| Policy | Required Role | Description |
+|--------|--------------|-------------|
+| `OwnerOnly` | Owner | Full system access including availability management |
+| `AdminOnly` | Owner or Admin | User management access |
+
+## Data Models
+
+### AuthResponse
+- `accessToken` — short-lived JWT (e.g. 15 min)
+- `refreshToken` — long-lived opaque token
+- `expiresAt` — access token expiry datetime
+- `user` — authenticated user info
+
+### ApplicationUser (returned in auth responses)
+- `id` — Guid
+- `email` — string
+- `naam` — string (display name)
+- `role` — string (Owner / Admin / User)
+- `isActive` — boolean
+
+### Invitation
+- `token` — string (URL-safe token)
+- `email` — string
+- `role` — string
+- `expiryDate` — datetime
+- `isUsed` — boolean