Welcome to Agora, the central public space and shared library repository for the odysseia-greek project.

In ancient Greece, the Agora was the heartbeat of the city-state. A place for gathering, commerce, and civic life. Similarly, this repository serves as the foundational cornerstone for our microservices architecture. It houses the shared packages, interfaces, and models used by nearly every other repository within the organization.

Agora is a poly-monorepo. While all code resides in this single repository, each package is designed to be independent, with its own go.mod file, allowing for granular versioning and minimal dependency bloat in downstream services.

The packages here range from stable core utilities to experimental services, all evolving to support the needs of the Odysseia-Greek project.

Shared Cache Interface Provides a unified interface for caching mechanisms, currently implementing BadgerDB for local key-value storage.

Elasticsearch Interface The primary bridge to Elasticsearch. It contains models and clients for searching, indexing, and managing documents across the Odysseia platform.

Vault & Security Interface Handles interactions with HashiCorp Vault for secret management, including Kubernetes authentication and secure retrieval of sensitive data.

gRPC Queue Service An ongoing experiment in building a high-performance gRPC-based queuing system for message passing between internal services.

Common Shared Layer The most widely used package in the organization. It contains common models (Solon, etc.), logging utilities, middleware, and helper functions used by almost all Go-based apps in the project.

Kubernetes Abstraction & CRDs Contains Kubernetes client wrappers and Custom Resource Definitions (CRDs) specific to the Odysseia infrastructure, such as service mappings.

Elasticsearch Seeder & Configuration Focused on the initialization and configuration of Elasticsearch, including index patterns, ILM policies, and role mappings.

Since Agora is a poly-monorepo, we do not release the entire repository under a single version. Instead, each package is released and versioned independently.

The Makefile at the root is the primary tool for managing these releases. It uses Git Tags following the format package/vX.Y.Z (e.g., plato/v0.2.12).

To run a command for a specific module, pass the MODULE variable (defaults to archytas if omitted).

• Get the latest version:

  make get-latest-version MODULE=plato

• Release a Patch (v0.1.2 -> v0.1.3):

  make release-patch MODULE=plato

• Release a Minor version (v0.1.2 -> v0.2.0):

  make release-minor MODULE=plato

• Release a Major version (v0.1.2 -> v1.0.0):

  make release-major MODULE=plato

This structure allows downstream projects to depend only on the specific parts of Agora they need (e.g., github.com/odysseia-greek/agora/plato) without pulling in unrelated dependencies like Vault or Elasticsearch clients. It also ensures that a breaking change in an experimental package (like Eupalinos) doesn't force a version bump across the entire organization.

We welcome contributions! Whether it's a bug fix, a new feature, or an improvement to an experimental package, please feel free to open a Pull Request.