I am batman

README.md

@@ -0,0 +1,169 @@
+# Go Microservices
+
+Go-based microservices backend with a REST API gateway, gRPC service-to-service communication, JWT auth, and local observability tooling.
+
+## Overview
+
+This repo contains:
+
+- `api-gateway`: public HTTP API (`/api/v1/*`)
+- `services/auth-service`: authentication and user auth workflows
+- `services/user-service`: user domain service
+- `services/post-service`: post domain service
+- `proto`: shared protobuf contracts used by gateway and services
+
+Core infra for local development includes PostgreSQL, Redis, Docker Compose, Prometheus, Grafana, and Jaeger.
+
+## Project Layout
+
+```text
+go-microservices/
+├── api-gateway/
+├── services/
+│   ├── auth-service/
+│   ├── user-service/
+│   └── post-service/
+├── proto/
+├── scripts/
+├── docker-compose.yml
+├── Makefile
+└── README.md
+```
+
+## Quick Start
+
+Prerequisites:
+
+- Go 1.21+
+- Docker + Docker Compose
+- `protoc`
+- `make`
+
+Local startup:
+
+```bash
+make dev-setup
+make db-up
+make proto
+
+# run each in separate terminals
+make run-auth
+make run-user
+make run-post
+make run-gateway
+```
+
+Docker-first startup:
+
+```bash
+make docker-build
+make docker-up
+make docker-logs
+```
+
+## API Summary
+
+Base URL: `http://localhost:8080/api/v1`
+
+Endpoints:
+
+- `GET /` health check
+- `POST /signup` register
+- `POST /signin` login (returns `access_token`, `refresh_token`)
+- `POST /validate` validate token
+- `POST /userinfo` protected endpoint (`Authorization: Bearer <token>`)
+- `POST /test` create test entry
+- `GET /tests` list test entries
+
+Typical auth flow:
+
+1. `POST /signup`
+2. `POST /signin`
+3. Use `access_token` as `Bearer` token on protected routes
+4. (Optional) `POST /validate`
+
+## Service Ports
+
+- API Gateway: `8080`
+- Auth gRPC: `50051`
+- User gRPC: `50052`
+- Post gRPC: `50053`
+- PostgreSQL: `5432`
+- Redis: `6379`
+- Grafana: `3000`
+- Prometheus: `9090`
+- Jaeger: `16686`
+
+## Testing Options
+
+### 1) Postman
+
+- Import `postman_collection.json`
+- Import `postman_environment.json`
+- Set `base_url=http://localhost:8080`
+- Run requests in this order: health -> signup -> signin -> validate -> userinfo -> test -> tests
+
+### 2) Posting (terminal TUI)
+
+```bash
+./scripts/posting-start.sh
+```
+
+Environment file used by Posting:
+
+- `~/.config/posting/collections/go_microservices/Go Microservices API.env`
+
+### 3) curl
+
+```bash
+# Health
+curl -X GET http://localhost:8080/api/v1/
+
+# Sign in
+curl -X POST http://localhost:8080/api/v1/signin \
+  -H "Content-Type: application/json" \
+  -d '{"email":"john@example.com","password":"SecurePassword123!"}'
+```
+
+## Common Make Targets
+
+- `make build` build all services
+- `make test` run tests
+- `make lint` run linting
+- `make format` format code
+- `make proto` regenerate protobuf output
+- `make db-up` / `make db-down` start/stop DB infra
+- `make docker-up` / `make docker-down` start/stop container stack
+
+## Protobuf Regeneration
+
+When proto contracts change, regenerate bindings:
+
+```bash
+make proto
+```
+
+Direct command example:
+
+```bash
+protoc --go_out=. --go-grpc_out=. proto/auth.proto
+```
+
+Generated files are expected in service proto directories such as:
+
+- `services/auth-service/proto/`
+- `services/user-service/proto/`
+- `services/post-service/proto/`
+
+## Troubleshooting
+
+- Port conflicts: stop local stack (`make docker-down`) and restart required services
+- DB errors: run `make db-down && make db-up`
+- Token errors (`401`): sign in again and ensure `Bearer` prefix is present
+- 404/connection errors: verify `base_url` and gateway process on `:8080`
+
+## Notes
+
+- API returns JSON for most responses; errors typically use `{ "error": "..." }`
+- JWT can be passed via `Authorization` header (or cookie where supported)
+- Keep docs and contract examples in sync when changing endpoint behavior