# NotePlace Backend Server

![Go](https://img.shields.io/badge/Go-1.16%2B-00ADD8?style=for-the-badge&logo=go)
![Gin Framework](https://img.shields.io/badge/Gin-Web%20Framework-008080?style=for-the-badge&logo=go)
![Google OAuth](https://img.shields.io/badge/Google%20OAuth-Authentication-4285F4?style=for-the-badge&logo=google)

NotePlace is a web application backend for rating and commenting on various aspects of places. This server provides a robust API for managing places, attributes, and user ratings, with a focus on a CLI-friendly Google OAuth 2.0 authentication flow.

## ✨ Features

*   **Place Management:** Create, retrieve, and list places.
*   **Rating System:** Users can create, update, and delete ratings for places and their specific attributes.
*   **Custom Attributes:** Define custom attributes that can be rated for different place categories.
*   **CLI-Friendly Google OAuth 2.0:** Secure authentication designed for command-line interactions.
*   **JSON File Persistence:** Simple, file-based data storage (`db.json`).

## 🚀 Getting Started

### Prerequisites

Before you begin, ensure you have the following installed:

*   **Go:** Version 1.25 or higher.
*   **Google Cloud Project:** With OAuth 2.0 credentials configured for a Desktop App (you'll need a Client ID and Client Secret).

### Installation & Setup

1.  **Clone the repository:**

    ```bash
    git clone https://github.com/your-username/noteplace.git
    cd noteplace
    ```

2.  **Configure Environment Variables:**

    Create a `.env` file in the project root and add your Google OAuth credentials:

    ```dotenv
    GOOGLE_CLIENT_ID=YOUR_GOOGLE_CLIENT_ID
    GOOGLE_CLIENT_SECRET=YOUR_GOOGLE_CLIENT_SECRET
    # Optional: IP=0.0.0.0
    # Optional: PORT=3001
    ```

3.  **Run the Server:**

    ```bash
    go run cmd/server.go
    ```

    The server will start on `http://localhost:3001` (or your configured `IP:PORT`). Data will be loaded from and saved to `db.json`.

## 🔑 API Authentication (CLI Flow)

NotePlace uses a unique CLI-friendly Google OAuth 2.0 flow:

1.  **Initiate Login:** Send a `GET` request to `/api/auth/google/cli/login`.
    ```bash
    curl http://localhost:3001/api/auth/google/cli/login
    ```
    The server will respond with a `verification_url` and a `user_code`.

2.  **Authorize in Browser:** Open the `verification_url` in your web browser, log in with your Google account, and enter the provided `user_code` to grant access.

3.  **Receive Session ID:** Once authorized, your initial `curl` command will complete, returning a session ID. Include this ID in the `Authorization` header for all subsequent authenticated API requests:

    ```bash
    Authorization: <YOUR_SESSION_ID>
    ```

## 📖 API Endpoints

All API routes are prefixed with `/api`.

### Examples

*   **Get All Places:**
    ```bash
    curl http://localhost:3001/api/places
    ```

*   **Create a New Place (Authenticated):**
    ```bash
    curl -X POST \
      -H "Authorization: <YOUR_SESSION_ID>" \
      -H "Content-Type: application/json" \
      -d '{"name":"The Grand Restaurant","category":"Restaurant","address":{"street":"123 Main St","city":"Anytown","state":"CA","zip":"12345","country":"USA"}}' \
      http://localhost:3001/api/places
    ```

*   **Create a Rating (Authenticated):**
    ```bash
    curl -X POST \
      -H "Authorization: <YOUR_SESSION_ID>" \
      -H "Content-Type: application/json" \
      -d '{"placeId":"place-001","attributeId":"attr-service","score":9,"comment":"Excellent service!"}' \
      http://localhost:3001/api/ratings
    ```

For a complete list of endpoints and their details, please refer to the `docs/DESIGN.md` file.

## 📂 Project Structure

```
.github/
├── workflows/             # GitHub Actions workflows
├── go.mod                 # Go module dependencies
├── go.sum                 # Go module checksums
├── db.json                # JSON file used for data persistence
├── DESIGN.md              # Detailed design document
├── cmd/
│   └── server.go          # Main application entry point
├── hack/
│   └── createPlace.sh     # Example script for creating a place
├── internal/
│   ├── api/               # HTTP handlers and routing
│   ├── auth/              # Google OAuth logic
│   ├── models/            # Go struct definitions for data models
│   └── store/             # Data access layer (JSON file operations)
└── test/
    └── ...                # Unit and integration tests
```

## 💡 Future Enhancements

*   Transition to a proper database (e.g., PostgreSQL, SQLite).
*   Implement more robust session management and JWT refresh tokens.
*   Develop a comprehensive frontend application.
*   Expand test coverage and CI/CD pipelines.