pull request

FRONTEND_DOCUMENTATION.md

@@ -0,0 +1,226 @@
+# NBAT Frontend - Complete Developer Documentation
+
+**Version:** 1.0  
+**Last Updated:** February 3, 2026  
+**Status:** ✅ Production Ready
+
+A modern Angular 17 single-page application for a property rental booking platform (Airbnb-like). This guide covers everything developers need to understand and work with the codebase.
+
+---
+
+## 📋 Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Architecture Overview](#architecture-overview)
+3. [Project Structure](#project-structure)
+4. [Technology Stack](#technology-stack)
+5. [Key Features](#key-features)
+6. [Core Services](#core-services)
+7. [State Management](#state-management)
+8. [HTTP Interceptors](#http-interceptors)
+9. [API Integration](#api-integration)
+10. [Routing](#routing)
+
+---
+
+## Architecture Overview
+
+**Stack:** Angular 17 (Standalone), TypeScript 5.2, SCSS, Signals, PrimeNG, HttpClient
+
+### Component Architecture
+
+```
+Angular App (4200)
+    ↓
+Layout (navbar, footer)
+    ↓
+Route Components (home, tenant, landlord, email-verified)
+    ↓
+Shared Components (reusable UI components)
+    ↓
+Services (auth, user, listing, booking)
+    ↓
+HTTP Interceptors (CSRF, Auth, Auth-Expired)
+    ↓
+Backend API (8080)
+```
+
+---
+
+## Project Structure
+
+```
+src/
+├── app/
+│   ├── core/                              # Core functionality
+│   │   ├── auth/
+│   │   │   ├── auth.service.ts           # Authentication logic
+│   │   │   ├── csrf.interceptor.ts       # CSRF token handling
+│   │   │   ├── auth.interceptor.ts       # Add auth headers
+│   │   │   └── auth-expired.interceptor.ts # Handle 401
+│   │   ├── user.service.ts               # User management
+│   │   ├── validation.service.ts         # Form validation
+│   │   └── error-handler.service.ts      # Error handling
+│   │
+│   ├── layout/                            # Layout components
+│   │   ├── navbar/
+│   │   │   ├── navbar.component.ts
+│   │   │   └── navbar.component.html
+│   │   └── footer/
+│   │
+│   ├── shared/                            # Shared components
+│   │   ├── property-card/
+│   │   ├── search-filter/
+│   │   ├── book-date/
+│   │   └── pipes & directives
+│   │
+│   ├── tenant/                            # Tenant features
+│   │   ├── tenant.component.ts
+│   │   ├── home/
+│   │   ├── search/
+│   │   ├── property-details/
+│   │   └── my-bookings/
+│   │
+│   ├── landlord/                          # Landlord features
+│   │   ├── landlord.component.ts
+│   │   ├── listings/
+│   │   ├── create-listing/
+│   │   └── manage-bookings/
+│   │
+│   ├── email-verified/                    # Email verification
+│   ├── app.config.ts                      # App configuration
+│   ├── app.routes.ts                      # Routing rules
+│   └── app.component.ts                   # Root component
+│
+├── environments/                          # Environment config
+│   ├── environment.ts (production)
+│   └── environment.development.ts
+│
+├── assets/                                # Static assets
+│   ├── fonts/
+│   ├── images/
+│   └── scss/
+│
+├── styles.scss                            # Global styles
+├── main.ts                                # Entry point
+└── index.html                             # HTML template
+```
+
+---
+
+## Technology Stack
+
+| Layer             | Technology         | Version |
+| ----------------- | ------------------ | ------- |
+| **Framework**     | Angular            | 17+     |
+| **Language**      | TypeScript         | 5.2     |
+| **Build**         | Webpack            | Latest  |
+| **UI Components** | PrimeNG            | Latest  |
+| **Styling**       | SCSS               | Latest  |
+| **HTTP**          | Angular HttpClient | 17+     |
+| **Forms**         | Reactive Forms     | 17+     |
+| **State**         | Signals            | 17+     |
+
+---
+
+## Key Features
+
+**Tenants:** Browse properties, search with filters, view details, check availability, create bookings, view bookings, become landlord
+
+**Landlords:** Create listings, manage listings, view bookings, track revenue, update details
+
+**Security:** OAuth2 (Auth0), session-based auth, CSRF protection, role-based access, automatic token refresh
+
+---
+
+## Core Services
+
+**AuthService:** login(), logout(), isAuthenticated(), getCurrentUser(), assignLandlordRole(), updateUserAuthorities()
+
+**UserService:** fetchUser(), getAuthenticatedUserFromSecurityContext(), updateUserRole()
+
+**ListingService:** getAllListingsByCategory(), searchListings(), getOneListing(), createListing(), getLandlordListings()
+
+**BookingService:** createBooking(), checkAvailability(), getMyBookings(), getLandlordBookings()
+
+---
+
+## Services
+
+All services use HttpClient with CSRF, Auth, and Auth-Expired interceptors.
+
+Error handling: Network errors, 401 Unauthorized (redirect to login), 403 Forbidden, 400 Bad Request, 500 Server errors
+
+---
+
+## Authentication Flow
+
+**Login:** User clicks Login → Redirect to Auth0 → User authenticates → Auth0 callback → Code exchange for token → Backend session → Redirect to home
+
+**Logout:** Click Logout → Clear session → Clear localStorage → Redirect to home
+
+---
+
+## State Management
+
+**Signals:** user = signal<User | null>(null), isLoading = signal(false), error = signal<string | null>(null)
+
+**Reactive Forms:** Use FormGroup with validators, check validity before submit
+
+**Effects:** Watch for state changes with effect(() => { ... })
+
+---
+
+## HTTP Interceptors
+
+**CSRF Interceptor:** Extracts XSRF-TOKEN from cookie, adds X-CSRF-TOKEN header to non-GET requests
+
+**Auth Interceptor:** Adds withCredentials: true for session-based authentication
+
+**Auth-Expired Interceptor:** Handles 401 errors by redirecting to login and clearing session
+
+---
+
+## Development Guide
+
+**Setup:** `npm install`
+
+**Start:** `npm start` or `ng serve` → http://localhost:4200
+
+**Proxy:** Development proxy (proxy.conf.mjs) forwards /api, /oauth2, /login, /assets to http://localhost:8080. Backend must be running on 8080.
+
+**Build:** `ng build` or `ng build --configuration production`
+
+**Test:** `ng test` or `ng test --code-coverage`
+
+**Standards:** Use standalone components, reactive forms, services for HTTP, follow Angular style guide, add unit tests
+
+---
+
+## API Integration
+
+Call backend APIs through services using HttpClient. Expected response: JSON with id, listingId, userId, dates, totalNights, totalPrice, status.
+
+**Example:**
+
+```typescript
+createBooking(booking: Booking): Observable<any> {
+  return this.http.post(`${this.apiUrl}/booking/create`, booking, { withCredentials: true });
+}
+```
+
+---
+
+## Routing
+
+**Routes:** Home, login, search, property/:id, booking/:listingId, my-bookings (authGuard), landlord (roleGuard), 404
+
+**Guards:** authGuard (requires authentication), roleGuard (requires landlord role)
+
+---
+
+## Styling
+
+**Global:** styles.scss with colors, mixins, utility classes
+
+**Component:** Component-level SCSS for component-specific styles