Initial commit

feat: create basic server to manage google oauth, account, sessions, places, attributes and ratings.
2025-09-19 02:43:04 -07:00
commit f1909da1ad
26 changed files with 2619 additions and 0 deletions
@@ -0,0 +1,130 @@
+# 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.