Hitobito

Hitobito is a Ruby on Rails‑based web application engineered to model and administer complex organizational hierarchies, membership data, events, courses, mailings, and inter‑group communication. Its core design revolves around a meta‑model that decouples the definition of group and role types from the runtime data, allowing each installation to tailor the structure to its own federation or club. The application exposes a rich REST‑style API, OAuth/OIDC authentication mechanisms, and webhooks for external integrations, making it a versatile platform for developers building bespoke administrative tools.

Architecture & Technical Stack

• Language & Framework: Ruby 3.x with Rails 7, leveraging ActiveRecord for ORM and ActionCable for real‑time updates.
• Database: PostgreSQL is the default relational store, chosen for its robust support of complex queries and JSONB columns that underpin dynamic group attributes.
• Background Jobs: Sidekiq runs under Redis, handling email campaigns, event registrations, and scheduled clean‑ups.
• Search & Full‑Text: ElasticSearch integration powers faceted search across members, events, and documents.
• Testing & CI: RSpec, Capybara, and RuboCop enforce code quality; GitHub Actions orchestrate CI pipelines.
• Containerization: Docker Compose manifests are provided for local development and can be extended to Kubernetes deployments via Helm charts.

Core Capabilities & APIs

Hitobito exposes a RESTful API that mirrors the UI’s resource hierarchy. Endpoints for groups, roles, people, events, and mailings support CRUD operations, bulk uploads (CSV), and pagination. OAuth2 scopes map to the permission system defined in group/role types, enabling fine‑grained access control. Webhooks allow external services to react to lifecycle events such as person.created or event.registered. The API is versioned, and the documentation resides in ReadTheDocs, offering example payloads and authentication flows.

Deployment & Infrastructure

Deployments are fully self‑hosted. The application can run on any platform that supports Ruby, PostgreSQL, Redis, and ElasticSearch. For production, the recommended stack includes:

• A NGINX reverse proxy with HTTPS termination.
• Puma as the Rails application server, configured for multi‑worker mode.
• Sidekiq workers managed by systemd or Docker Swarm.
• A Redis cluster for job queuing and session storage.
• ElasticSearch nodes scaled horizontally to accommodate search load.

The provided Docker images simplify onboarding, while the Helm charts enable declarative Kubernetes deployments. Horizontal scaling is straightforward: each component can be replicated, and the Rails app reads from a shared PostgreSQL cluster.

Integration & Extensibility

Hitobito’s plugin architecture is a key differentiator. Plugins are plain Rails engines that can:

• Define new group types and role hierarchies, as shown in the README’s example.
• Add custom models, controllers, and views while inheriting shared logic.
• Register background jobs or webhook endpoints.
• Extend the API by adding new routes and serializers.

The open‑source community provides a wealth of plugins—hitobito_generic, hitobito_events, and others—that can be forked or extended. Developers can also hook into the event system to trigger external workflows, such as synchronizing members with a CRM or pushing notifications to Slack.

Developer Experience

The project offers comprehensive documentation across multiple domains: architecture, API reference, plugin development guide, and deployment instructions. The codebase follows Rails conventions, which reduces the learning curve for seasoned Ruby developers. Automated tests cover 90 % of the code, and continuous integration ensures regressions are caught early. The community is active on GitHub Issues and Discord, providing timely support for integration questions.

Use Cases

• Federated Associations: A national federation can model regional chapters, local clubs, and individual members with distinct role types while sharing a single data store.
• Event‑Centric Clubs: Organizations that run courses and workshops can leverage Hitobito’s registration engine, wait‑list logic, and qualification tracking.
• Custom Membership Portals: Developers can build lightweight front‑ends that consume the API, enabling mobile apps or embedded widgets.
• Data Migration: The CSV import tools and API allow gradual migration from legacy systems into Hitobito without data loss.

Advantages

• Performance: Rails’ eager loading and PostgreSQL indexes keep queries fast even with thousands of groups and millions of members.
• Flexibility: The meta‑model lets organizations define arbitrary hierarchies without code changes to the core.
• Licensing: MIT‑style license permits commercial use and modification, making it suitable for both non‑profits and enterprises.
• Community & Support: A mature ecosystem of plugins, active contributors, and extensive documentation reduces integration friction.

In summary, Hitobito offers a robust, extensible foundation for developers tasked with building or integrating complex membership and event management solutions in a self‑hosted environment.