316 lines
13 KiB
Markdown
316 lines
13 KiB
Markdown
# 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.
|