event-manager

module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 19, 2025 License: MIT

README

event-manager

Go version Go Reference Go Report Card License

A microservices-based event management system with REST/gRPC API, scheduler, and async notifications.

Table of Contents

Features

  • ✅ Events service: REST/gRPC API for managing events (CRUD, filters, reminders)
  • ✅ Scheduler: background service for notifications and periodic cleanup
  • ✅ Sender: async notification processor (RabbitMQ consumer)
  • ✅ Full observability: structured logging, middleware, context propagation
  • ✅ Resilience: retries, timeouts, graceful shutdown
  • ✅ Kubernetes & Helm: production-ready deployment
  • ✅ Docker Compose & Makefile: local development and testing
  • ✅ Integration tests: isolated environment with test DB and RabbitMQ

Architecture

┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│   events    │ │  scheduler  │ │   sender    │
│ (API gRPC)  │ │  (Producer) │ │  (Consumer) │
└─────┬───────┘ └──────┬──────┘ └──────┬──────┘
      │                │               │
      ▼                ▼               ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ PostgreSQL  │ │  RabbitMQ   │ │   stdout    │
└─────────────┘ └─────────────┘ └─────────────┘

Services

events — Event API Service

Handles creation, update, deletion, and querying of events via REST and gRPC.
Uses PostgreSQL for persistence and supports filtering by user, day, week, month, and custom period.
All operations are exposed as clean API endpoints.

Key endpoints:

  • POST /v1/events — create event
  • PUT /v1/events/{id} — update event
  • DELETE /v1/events/{id} — delete event
  • GET /v1/events/{id} — get event by ID
  • GET /v1/events/user/{user_id} — get all events for user
  • GET /v1/events/day, /week, /month, /period — time-based filters

Swagger UI: http://localhost:8888/swagger/swagger.json (also accessible by ./api/events/v1/EventsService.swagger.json)

scheduler — Background Worker

Runs periodically to:

  • Scan for events requiring notifications (based on remind_in).
  • Send notification messages to RabbitMQ.
  • Clean up old (past) events from the database.

Does not expose an API — runs as a daemon.
Relies on the same PostgreSQL and RabbitMQ as events.

sender — Notification Consumer

Listens to RabbitMQ queue for notification messages.
On receipt, prints notification to stdout (simulating delivery via email, push, etc.).

Used to decouple notification logic and support async delivery.
Can be extended to integrate with real delivery services.

Quick Start

# Start all services
make up

# Stop services
make down

# Stop and clean everything (including volumes and networks)
make down-clean
With Kubernetes (Minikube + Helm)
# Deploy entire system
make chart-run

# Stop cluster
make chart-stop

# Removes all traces of the cluster
make cluster-delete

💡 After make chart-run, the services are exposed via Ingress. Use minikube service list to see available endpoints or minikube dashboard to get the access directly to the dashboard.

Integration Tests
# Run full integration test suite
make integration-tests

Running Services Without Docker

You can run services directly (e.g. for debugging), but external dependencies (PostgreSQL, RabbitMQ) are still managed via Docker:

# Start database and message queue
make infrastructure-up

# Build and run services manually
make run-events
make run-scheduler
make run-sender

⚠️ Note: Update service configs to use localhost instead of container hosts or 0.0.0.0.

System Requirements

To run or deploy the system, ensure the following tools are installed:

  • Docker and Docker Compose — for local development and testing
  • kubectl — for Kubernetes interaction
  • minikube v1.36+ — for local cluster deployment
  • Helm v3.18+ — for templating and deploying manifests
  • Go v1.24.2+ — only if building from source or running services directly

Additional Make Commands

The Makefile also supports:

  • make build — build all binaries
  • make test — run unit tests
  • make lint — run linter
  • make migrate-up — apply DB migrations
  • make setup-tools — install gRPC depencdecies, mockery, goose

Configuration

All services are configured via TOML files (./configs/*/config.toml) with environment override support (prefix: EVENTS_).

Directories

Path Synopsis
api
events/v1
Package v1 is a reverse proxy.
 Package v1 is a reverse proxy.
cmd
events command
Package main contains entrypoint for the events service.
 Package main contains entrypoint for the events service.
scheduler command
Package main contains entrypoint for the scheduler service.
 Package main contains entrypoint for the scheduler service.
sender command
Package main contains entrypoint for the sender service.
 Package main contains entrypoint for the sender service.
internal
app
Package app provides events service with business logic handling.
 Package app provides events service with business logic handling.
app/mocks
config/events
Package events provides configuration structures for the service.
 Package events provides configuration structures for the service.
config/scheduler
Package scheduler provides configuration structures for the service.
 Package scheduler provides configuration structures for the service.
config/sender
Package sender provides configuration structures for the service.
 Package sender provides configuration structures for the service.
dto
Package dto provides data transfer objects for the events service.
 Package dto provides data transfer objects for the events service.
errors
Package errors contains errors used in the project.
 Package errors contains errors used in the project.
scheduler
Package scheduler provides an events scheduler, which is responsible for queuing the storage for events which need notifications and cleaning up old events from the storage.
 Package scheduler provides an events scheduler, which is responsible for queuing the storage for events which need notifications and cleaning up old events from the storage.
sender
Package sender provides an events sender, which is responsible for queuing the message queue for notifications and their sending.
 Package sender provides an events sender, which is responsible for queuing the message queue for notifications and their sending.
server/grpc
Package grpc provides a gRPC server implementation.
 Package grpc provides a gRPC server implementation.
server/grpc/mocks
server/http
Package http contains the implementation of the HTTP server.
 Package http contains the implementation of the HTTP server.
storage
Package storage provides a storage interface and factory method for storage construction.
 Package storage provides a storage interface and factory method for storage construction.
storage/memory
Package memory provides an in-memory storage implementation.
 Package memory provides an in-memory storage implementation.
storage/sql
Package sql provides a SQL database storage implementation.
 Package sql provides a SQL database storage implementation.
storage/sql/mocks
types
Package types contains Event type and its constructor and helper functions.
 Package types contains Event type and its constructor and helper functions.
pkg
config
Package config provides configuration loader and the interface for working with configuration.
 Package config provides configuration loader and the interface for working with configuration.
logger
Package logger package provides a constructor and wrapper methods for an underlying logger (currently - slog.Logger).
 Package logger package provides a constructor and wrapper methods for an underlying logger (currently - slog.Logger).
rabbitmq
Package rabbitmq provides a RabbitMQ client, which is suitable for sending and receiving messages.
 Package rabbitmq provides a RabbitMQ client, which is suitable for sending and receiving messages.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.