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

Clone the repository:

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

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

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:

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

4.7 KiB Raw Blame History