From 19ae27a404ec46e76a709498f406cadca70f6610 Mon Sep 17 00:00:00 2001
From: Arnaud Delcasse <arnaud.delcasse@mobicoop.org>
Date: Mon, 5 Jan 2026 19:13:29 +0100
Subject: [PATCH] Add REASDME

---
 README.md | 142 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 142 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..10dd35a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,142 @@
+# Saved Search Service
+
+A GRPC microservice for managing saved journey searches in the COOPGO platform. Users can save, retrieve, update, and delete their journey searches with departure/destination locations stored as GeoJSON features.
+
+## Features
+
+- Create, read, update, and delete saved searches
+- GeoJSON support for departure and destination locations
+- Owner-based access control
+- Paginated listing with filtering
+- MongoDB storage backend
+
+## Requirements
+
+- Go 1.22+
+- MongoDB
+- Protocol Buffers compiler (for regenerating proto files)
+
+## Configuration
+
+Configuration is managed via Viper and can be set through a `config.yaml` file or environment variables.
+
+### Default Configuration
+
+```yaml
+name: "COOPGO Saved Search Service"
+dev_env: false
+
+storage:
+  db:
+    type: mongodb
+    mongodb:
+      host: localhost
+      port: 27017
+      db_name: coopgo_platform
+      collections:
+        saved_searches: saved_searches
+
+services:
+  grpc:
+    enable: true
+    port: 8080
+```
+
+### Environment Variables
+
+Configuration keys can be set via environment variables by replacing `.` with `_`:
+
+- `STORAGE_DB_MONGODB_HOST` - MongoDB host
+- `STORAGE_DB_MONGODB_PORT` - MongoDB port
+- `SERVICES_GRPC_PORT` - GRPC server port
+- `DEV_ENV` - Enable development mode (pretty logging)
+
+## Building
+
+```bash
+go build -o saved-search
+```
+
+## Running
+
+```bash
+./saved-search
+```
+
+## Docker
+
+Build the Docker image:
+
+```bash
+docker build \
+  --build-arg ACCESS_TOKEN_USR=<git_username> \
+  --build-arg ACCESS_TOKEN_PWD=<git_token> \
+  -t saved-search .
+```
+
+Run the container:
+
+```bash
+docker run -p 8080:8080 saved-search
+```
+
+## API
+
+The service exposes a GRPC API with the following methods:
+
+| Method | Description |
+|--------|-------------|
+| `CreateSavedSearch` | Create a new saved search |
+| `GetSavedSearch` | Get a saved search by ID |
+| `GetSavedSearchesByOwner` | Get all saved searches for an owner |
+| `UpdateSavedSearch` | Update an existing saved search |
+| `DeleteSavedSearch` | Delete a saved search |
+| `ListSavedSearches` | List saved searches with pagination |
+
+### SavedSearch Structure
+
+```protobuf
+message SavedSearch {
+    string id = 1;
+    string owner_id = 2;
+    SavedSearchGeoJsonFeature departure = 3;
+    SavedSearchGeoJsonFeature destination = 4;
+    google.protobuf.Timestamp datetime = 5;
+    google.protobuf.Struct data = 6;
+    google.protobuf.Timestamp created_at = 7;
+    google.protobuf.Timestamp updated_at = 8;
+}
+```
+
+## Project Structure
+
+```
+saved-search/
+├── main.go                 # Application entry point
+├── config.go               # Configuration management
+├── core/
+│   └── service/            # Business logic layer
+├── data/
+│   ├── types/              # Data types
+│   └── storage/            # Storage implementations (MongoDB)
+└── servers/
+    └── grpc/
+        ├── proto/          # Protocol buffer definitions
+        └── server/         # GRPC server implementation
+```
+
+## Regenerating Proto Files
+
+```bash
+protoc --go_out=. --go-grpc_out=. servers/grpc/proto/saved-search.proto
+```
+
+## Testing
+
+```bash
+go test ./...
+```
+
+## License
+
+This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).