noteplace-server/docs/FRONTEND_DESIGN.md

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.

// 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):

  {
    "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:

  {
    "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:

  {
    "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:

  {
    "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:

  {
    "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.