131 lines
4.7 KiB
Markdown
131 lines
4.7 KiB
Markdown
# 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:**
|
|
|
|
```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.
|