noteplace-server/README.md

NotePlace Backend Server

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:

   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:

   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:

   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.

   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:

   Authorization: <YOUR_SESSION_ID>
   

📖 API Endpoints

All API routes are prefixed with /api.

Examples

• Get All Places:

  curl http://localhost:3001/api/places
  

• Create a New Place (Authenticated):

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

  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.