🧩 ActivityMaster Core

Open-source implementation of the Functional Service Data Model (FSDM) services — Enterprise, Address, Events, Arrangements, ResourceItem, Classification, and the supporting security/ActiveFlag infrastructure. Built on Java 25+, Vert.x 5, GuicedEE, Hibernate Reactive 7, and PostgreSQL, the library exposes Guice client interfaces so downstream applications can manage the canonical warehouse schema without a dedicated desktop client.

Built on Vert.x 5 · Google Guice · Hibernate Reactive · Mutiny · JPMS module com.guicedee.activitymaster · Java 25+

✨ Features

• Canonical FSDM domain services — Enterprise, Address, Events, Arrangements, ResourceItem, Classification
• Reactive persistence — Hibernate Reactive 7 + PostgreSQL via Vert.x reactive SQL clients
• Vert.x 5 integration — async workflows, event-bus messaging, and verticle deployment
• GuicedEE DI bootstrap — lifecycle hooks, post-startup actions, and ServiceLoader-driven module discovery
• Security token propagation — SecurityToken metadata on every service call with ActiveFlag row-state enforcement
• Enterprise lifecycle — createNewEnterprise → loadUpdates → startNewEnterprise bootstrapping order with ISystemUpdate/@SortedUpdate classification loading and IPasswordsService admin registration

📦 Installation

<dependency>
  <groupId>com.activity-master</groupId>
  <artifactId>activity-master</artifactId>
</dependency>

Gradle (Kotlin DSL)

implementation("com.activity-master:activity-master")

🚀 Quick Start

cp .env.example .env   # update DB credentials + toggles
mvn -B clean verify    # compilation + tests (uses Testcontainers)

Consume services via the Activity Master Client module in your host app.

⚙️ Configuration

Environment Variables

Copy .env.example to .env for local development. Keep secrets out of version control.

Variable	Purpose	Default
DB_URL	Database JDBC URL	—
DB_USER	Database username	—
DB_PASS	Database password	—
JWT_TEST_TOKEN	JWT token for test harness	—
TEST_DB_CONTAINER_IMAGE	Testcontainers Postgres image	postgres:latest
OAUTH2_ISSUER_URL	OAuth2 issuer URL	—
JWKS_URI	JSON Web Key Set URI	—
ENVIRONMENT	Runtime environment	dev

CI secrets (SONA_USERNAME, SONA_PASSWORD, GPG_PRIVATE_KEY, GPG_PASSPHRASE, GITHUB_ACTOR, GITHUB_TOKEN) are managed via GitHub Actions repository/environment secrets.

🧩 JPMS & SPI

Module name: com.guicedee.activitymaster

JPMS-friendly with ServiceLoader discovery for DI and lifecycle hooks.

module my.app {
    requires com.guicedee.activitymaster;
    requires com.guicedee.client;
    requires com.guicedee.persistence;

    opens my.app.entities to org.hibernate.orm.core, com.google.guice, com.entityassist;
    opens my.app.services to com.google.guice;

    provides com.guicedee.client.services.lifecycle.IGuiceModule
        with my.app.AppModule;
}

🧪 Testing

The test harness uses Testcontainers to spin up a PostgreSQL instance automatically. Tests enforce the enterprise lifecycle order:

1. createNewEnterprise — bootstrap the enterprise
2. loadUpdates — classifications and types loaded via ISystemUpdate/@SortedUpdate
3. startNewEnterprise — admin user registered through IPasswordsService, post-startup actions execute

# Run all tests
mvn -B clean verify

# Skip integration tests
mvn -B clean verify -DskipITs

CI via .github/workflows/maven-verify.yml installs Java 25, sets the required secrets, and executes mvn -B verify.

🧰 Troubleshooting & Best Practices

• Verify .env is present for local runs and matches the required variables
• Every service propagates SecurityToken metadata and respects ActiveFlag row status — changes in capabilities must describe how value-level access is enforced
• Keep transactions short; chain Uni calls and reuse a single session within withTransaction
• Use Testcontainers for local integration testing to avoid external database dependencies

🤝 Contributing

Issues and pull requests are welcome.

• Follow existing code style and patterns
• Include tests for new features
• Update documentation for behavior changes
• Ensure JPMS module-info.java is correct
• Run mvn -B clean verify before submitting a PR

📄 License

Apache 2.0

Repository & Links

• GitHub: https://github.com/Activity-Master/Core
• Issues: https://github.com/Activity-Master/Core/issues
• Pull Requests: https://github.com/Activity-Master/Core/pulls