ofelia-core

ofelia-core is the core engine shard for Project Ofelia SaaS applications. Designed around strict hexagonal architecture, it encapsulates Identity and Access Management (IAM), security handlers (Rate Limiting, Security Headers, PostgreSQL Sessions), abstract job queue routing (QueueRouter), and multi-provider cloud storage management (Storage::Manager).

Features & Design Principles

• Strict Hexagonal Boundary: ofelia-core owns engine-level security, session management, and abstract interfaces. Host applications (ofelia-template derivatives) own domain models, presentation layers, and deployment config.
• Zero-Extra-Infrastructure: Session persistence and queue management rely exclusively on PostgreSQL 18.
• Compile-Time Configuration: Eliminates runtime YAML files in favor of strongly-typed Crystal configuration structs (Ofelia::Core::Config).
• GPLv3 Licensed: Released under the GNU General Public License v3.0.

Official Repository

The official repository for ofelia-core is hosted on GitLab: https://gitlab.com/renich/ofelia-core

Installation

Add ofelia-core to your application's shard.yml:

dependencies:
  ofelia-core:
    gitlab: renich/ofelia-core
    version: ~> 0.1.0

Run shards install.

Modules & Services

1. Engine Bootloader & Config

require "ofelia-core"

# Construct strongly-typed configuration from 12-Factor ENV vars
config = Ofelia::Core::Config.new(
  database_url: ENV["DATABASE_URL"],
  session_secret: ENV["SESSION_SECRET"],
  rate_limit_max: (ENV["RATE_LIMIT_MAX"]? || "100").to_i
)

# Boot core engine
Ofelia::Core.boot!(config)

2. Job Queue Routing (QueueRouter)

Transparently dispatches background tasks to PostgreSQL (crystal-pg-queue) or GCP Cloud Tasks (gcs-crest) based on JOB_EXECUTION_MODE:

# Enqueue job via unified router
Ofelia::Core::Jobs::QueueRouter.enqueue(MyJob.new(args))

3. Unified Storage Manager (Storage::Manager)

Switches between local filesystem volume storage (development) and Google Cloud Storage (production):

storage = Ofelia::Core::Storage::Manager.provider
storage.write("uploads/document.pdf", file_bytes, "application/pdf")

Running Specs

crystal spec

License

GNU General Public License v3.0 (GPL-3.0-or-later). See LICENSE for details.

Author

Created and maintained by Rénich Bon Ćirić (renich@woralelandia.com).