# Frontend Design Document - Noteplace

## 1. Introduction
This document outlines the frontend design for the Noteplace application, focusing on user experience, functionality, and technical considerations for a modern, cross-platform web application with a native-like mobile experience.

## 2. Core Principles
*   **User-Centric Design:** Intuitive, easy-to-use interface.
*   **Responsive & Adaptive:** Seamless experience across desktop and mobile devices.
*   **Performance:** Fast loading times and smooth interactions.
*   **Modern UI/UX:** Clean, aesthetically pleasing, and consistent design.
*   **Progressive Web App (PWA):** Native-like capabilities on mobile, especially for iOS "Add to Home Screen."

## 3. Technology Stack (Proposed)
*   **Framework:** React (with TypeScript) for robust component-based development.
*   **Styling:** Tailwind CSS for utility-first styling, enabling rapid UI development and responsiveness. Material Design principles will guide the overall aesthetic.
*   **State Management:** React Context API or Zustand for simple, scalable state management.
*   **Routing:** React Router for declarative navigation.
*   **API Communication:** Fetch API or Axios for interacting with the backend.
*   **Mapping:** Google Maps JavaScript API for interactive maps and place search.

## 4. Frontend Functionalities

### 4.1. User Authentication
*   **Login/Signup:** Integration with Google OAuth (as per `internal/auth/google.go`).
*   **Session Management:** Secure handling of user sessions.

### 4.2. Place Management
*   **Create Place:**
    *   User inputs place name and category.
    *   **Google Maps Integration:** As the user types, suggest real places using Google Places Autocomplete API.
    *   Upon selection, populate address fields (`Street`, `City`, `State`, `Zip`, `Country`) from Google Places details.
    *   Optionally, display a map preview of the selected location.
    *   Submit to backend to create the `Place` entry.
*   **View Place Details:** Display place name, category, address, and a list of associated ratings and attributes.
*   **Search Places:** Allow users to search for existing places by name, category, or address components.

### 4.3. Rating Management
*   **Add Rating:**
    *   Accessed from a Place's detail view.
    *   User provides a score (1-10) and an optional comment.
    *   **Attribute Integration:**
        *   Frontend will fetch relevant attributes for the place using `GET /api/places/:id/attributes`.
        *   Display these existing attributes (e.g., "Ambiance" for a "Restaurant").
        *   Allow users to search for and select existing attributes.
        *   If an attribute doesn't exist, provide an option to create it (see 4.4. Create Attribute). The newly created attribute can then be selected for the rating.
        *   Submitting a rating will call `POST /api/ratings` with `placeId`, `attributeId`, `score`, and `comment`.
*   **View Ratings:**
    *   For a specific place, ratings will be fetched using `GET /api/places/:id/ratings`.
    *   For the current user, ratings will be fetched using `GET /api/ratings/my-ratings`.
    *   Display individual ratings with score, comment, associated attribute, and user.
*   **Edit/Delete Rating:**
    *   Allow users to edit their own ratings, calling `PUT /api/ratings/:id` to update `score` and `comment`.
    *   Allow users to delete their own ratings, calling `DELETE /api/ratings/:id`.

### 4.4. Attribute Management
*   **Search Attributes:**
    *   While creating a rating, users can search for existing attributes. This will likely involve a frontend-side search/filter of attributes already fetched or a dedicated backend search endpoint (if available, otherwise a comprehensive `GET /api/attributes` would be needed, which is not currently defined in `DESIGN.md`). For now, assume attributes are fetched per place or a general list is available.
*   **Create Attribute:**
    *   When an attribute doesn't exist during rating creation, the user can define a new one.
    *   The frontend will prompt for `Name`, `Scope` (CATEGORY or PLACE), and `OwnerID` (e.g., `placeCategory` for `CATEGORY` scope, or `placeId` for `PLACE` scope).
    *   This will call `POST /api/attributes` to create the new attribute.

### 4.5. User Profile
*   **View Profile:** Display user's `DisplayName`, `Email`, `Role`, and `CreatedAt`.
*   **Edit Profile:** (Future consideration) Allow users to update display name or other non-critical information.
*   **User's Activity:** Show a summary of places created, ratings given, etc.

## 5. Pages and Views

### 5.1. Authentication Views
*   **Login Page:** Simple page with "Sign in with Google" button.
*   **Loading/Redirect Page:** For OAuth flow.

### 5.2. Main Application Views
*   **Dashboard/Home Page:**
    *   Overview of recent activity (e.g., recently rated places, trending attributes).
    *   Quick access to "Create New Place" and "Search Places."
*   **Place List/Search Results Page:**
    *   Displays a list of places, filterable and sortable.
    *   Each item shows key information (name, category, address snippet).
    *   Should have map and list views.
*   **Place Detail Page:**
    *   Prominent display of place information.
    *   Section for "Ratings" (list of all ratings for this place).
    *   Button to "Add New Rating."
    *   Section for "Attributes" (list of attributes associated with this place/category).
*   **Create/Edit Place Form:** Guided form for adding new places, with Google Maps integration.
*   **Add Rating Form:** Form for submitting a rating, including attribute selection/creation.
*   **User Profile Page:** Displays user details and activity.

## 6. Desktop and Mobile Support

### 6.1. Responsive Design
*   The UI will be built using a mobile-first approach, ensuring optimal layout and usability on small screens.
*   Tailwind CSS will be used to implement responsive breakpoints, adapting layouts, font sizes, and component visibility for larger screens (tablets, desktops).

### 6.2. Mobile-Specific Enhancements
*   **Touch-Friendly Interactions:** Larger tap targets, swipe gestures where appropriate.
*   **Optimized Navigation:** Bottom navigation bar for primary actions on mobile.
*   **Performance:** Lazy loading of components and data, image optimization.

### 6.3. iOS "Add to Home Screen" (PWA)
To provide a native-like experience on iOS when users add the web application to their home screen, the following PWA features will be implemented:
*   **Web App Manifest:** A `manifest.json` file will define the app's name, icons, start URL, display mode (`standalone`), and theme colors.
*   **Service Worker:** A service worker will be registered to enable:
    *   **Offline Capabilities:** Caching essential assets and data for offline access.
    *   **Faster Loading:** Instant loading on subsequent visits.
    *   **Push Notifications:** (Future consideration) If backend supports it.
*   **Meta Tags:** Specific `<meta>` tags in the HTML head will configure iOS behavior, such as `apple-mobile-web-app-capable`, `apple-mobile-web-app-status-bar-style`, and `apple-mobile-web-app-title`.
*   **Splash Screen:** Custom splash screens will be configured via meta tags and manifest for a branded launch experience.

## 7. UI/UX Modernity
*   **Clean Typography:** Use modern, readable sans-serif fonts.
*   **Consistent Color Palette:** A well-defined primary, secondary, and accent color palette, adhering to accessibility standards.
*   **Intuitive Iconography:** Use a consistent icon set (e.g., Material Icons).
*   **Subtle Animations & Transitions:** Enhance user feedback and perceived performance.
*   **Card-Based Layouts:** For displaying lists of places, ratings, and attributes, providing clear visual separation.
*   **Form Design:** Clear labels, input validation feedback, and accessible controls.
*   **Dark Mode:** (Future consideration) Offer a dark theme option.

## 8. Backend API Reference for Frontend
This section provides a detailed overview of the backend API endpoints, including their expected request and response structures, to serve as a clear contract for frontend development.

### 8.1. Data Models (JSON Representation)
These are the core data structures as they will be sent/received in JSON format.

```json
// User
{
  "id": "string",
  "googleId": "string",
  "displayName": "string",
  "email": "string",
  "role": "number", // 0: ADMIN, 1: TRUSTED, 2: USER
  "createdAt": "string" // ISO 8601 format
}

// Session
{
  "id": "string",
  "userId": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

// Address
{
  "street": "string",
  "city": "string",
  "state": "string",
  "zip": "string",
  "country": "string"
}

// Place
{
  "id": "string",
  "name": "string",
  "category": "string",
  "address": {
    "street": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "country": "string"
  },
  "createdAt": "string" // ISO 8601 format
}

// Attribute
{
  "id": "string",
  "name": "string",
  "scope": "number", // 0: CATEGORY, 1: PLACE
  "ownerID": "string", // Category ID if scope is CATEGORY, Place ID if scope is PLACE
  "description": "string", // Optional
  "attachment": "string" // Optional
}

// Rating
{
  "id": "string",
  "placeId": "string",
  "attributeId": "string",
  "userId": "string",
  "score": "number", // 1-10
  "comment": "string", // Optional
  "createdAt": "string" // ISO 8601 format
}
```

### 8.2. Authentication Endpoints

#### `GET /api/auth/google/cli/login`
*   **Description:** Initiates the CLI login process.
*   **Request:** No body.
*   **Response (200 OK):**
    ```json
    {
      "verification_url": "string",
      "user_code": "string"
    }
    ```

#### `POST /api/auth/logout`
*   **Description:** Logs the user out (invalidates the session).
*   **Request:** No body.
*   **Headers:** `Authorization: <YOUR_SESSION_ID>`
*   **Response (200 OK):** No body.

### 8.3. Place Endpoints

#### `GET /api/places`
*   **Description:** Retrieves a list of all places.
*   **Request:** No body.
*   **Response (200 OK):** `Array<Place>`

#### `POST /api/places`
*   **Description:** Creates a new place.
*   **Headers:** `Authorization: <YOUR_SESSION_ID>`, `Content-Type: application/json`
*   **Request Body:**
    ```json
    {
      "name": "string",
      "category": "string",
      "address": {
        "street": "string",
        "city": "string",
        "state": "string",
        "zip": "string",
        "country": "string"
      }
    }
    ```
*   **Response (201 Created):** `Place`

#### `GET /api/places/:id`
*   **Description:** Retrieves details for a single place.
*   **Request:** No body.
*   **Response (200 OK):** `Place`

#### `GET /api/places/:id/ratings`
*   **Description:** Retrieves all ratings for a specific place.
*   **Request:** No body.
*   **Response (200 OK):** `Array<Rating>`

#### `GET /api/places/:id/attributes`
*   **Description:** Retrieves relevant attributes for a place (based on its category and specific place attributes).
*   **Request:** No body.
*   **Response (200 OK):** `Array<Attribute>`

### 8.4. Rating Endpoints

#### `POST /api/ratings`
*   **Description:** Creates a new rating.
*   **Headers:** `Authorization: <YOUR_SESSION_ID>`, `Content-Type: application/json`
*   **Request Body:**
    ```json
    {
      "placeId": "string",
      "attributeId": "string",
      "score": "number", // 1-10
      "comment": "string" // Optional
    }
    ```
*   **Response (201 Created):** `Rating`

#### `PUT /api/ratings/:id`
*   **Description:** Updates an existing rating.
*   **Headers:** `Authorization: <YOUR_SESSION_ID>`, `Content-Type: application/json`
*   **Request Body:**
    ```json
    {
      "score": "number", // 1-10
      "comment": "string" // Optional
    }
    ```
*   **Response (200 OK):** `Rating`

#### `DELETE /api/ratings/:id`
*   **Description:** Deletes a rating.
*   **Headers:** `Authorization: <YOUR_SESSION_ID>`
*   **Request:** No body.
*   **Response (204 No Content):** No body.

#### `GET /api/ratings/my-ratings`
*   **Description:** Retrieves all ratings made by the authenticated user.
*   **Headers:** `Authorization: <YOUR_SESSION_ID>`
*   **Request:** No body.
*   **Response (200 OK):** `Array<Rating>`

### 8.5. Attribute Endpoints

#### `POST /api/attributes`
*   **Description:** Creates a new attribute.
*   **Headers:** `Authorization: <YOUR_SESSION_ID>`, `Content-Type: application/json`
*   **Request Body:**
    ```json
    {
      "name": "string",
      "scope": "number", // 0: CATEGORY, 1: PLACE
      "ownerID": "string", // Required. Category ID if scope is CATEGORY, Place ID if scope is PLACE
      "description": "string", // Optional
      "attachment": "string" // Optional
    }
    ```
*   **Response (201 Created):** `Attribute`

## 9. Future Considerations
*   **Push Notifications:** For new ratings on followed places or attributes.
*   **User Following:** Follow other users to see their ratings.
*   **Image Uploads:** For places and attributes.
*   **Advanced Search Filters:** More granular filtering for places and ratings.
*   **Localization:** Support for multiple languages.
*   **Accessibility:** Comprehensive WCAG compliance.