Local development
Repository layout, local stack, build profiles, and where to change the UI, API, and stream providers.
EventOre is an open-source monorepo. Operators use the getting started guide; this page is for engineers extending or debugging the product. To contribute, see How to contribute.
Technology stack
| Area | Stack |
|---|---|
| Backend | Java 21, Spring Boot 3.3, modular Maven providers, OpenAPI 3, WebSocket + SSE |
| Frontend | Vite, React, TypeScript, nginx in cluster images |
| MCP (optional) | Node.js — mcp/eventore-mcp |
| Deploy | Docker, Helm (OCI on GHCR), GitHub Actions for images and docs |
Repository layout
backend/ Spring Boot API and eventore-provider-* modules
frontend/ React console
docs/ Product site (GitHub Pages)
openapi/ API contracts and codegen
mcp/eventore-mcp/ Optional MCP server
deploy/helm/ Kubernetes charts
docker/ Dockerfiles and broker compose for local dev
Deep dive: Architecture · Control & data plane
Prerequisites
- Java 21+ and Maven 3.9+
- Node.js 20+ for the frontend (and MCP if you work on it)
- Docker for test brokers and optional full stack
Local development
1. Test brokers
docker compose -f docker/docker-compose.brokers.yml up -d
2. Backend
cd backend
mvn -pl eventore-server -am spring-boot:run -Dspring-boot.run.profiles=local
- Swagger UI:
http://localhost:8080/swagger-ui.html - OpenAPI:
http://localhost:8080/openapi/eventore-api.yaml - Loaded providers:
GET /api/v1/providers
Module layout and Maven profiles: backend/README.md in the repository.
3. Frontend
cd frontend
npm install
npm run dev
Open http://localhost:5173 — the dev server proxies API calls to the backend.
4. Full stack (optional)
docker compose -f docker/docker-compose.stack.yml up -d
Slim builds (providers)
Ship only the protocols you need at build and runtime:
- Maven profile on
eventore-server(e.g.-Pkafka-kinesis -P!providers-all) eventore.enabled-protocolsor HelmenabledProtocols- UI reads
GET /api/v1/config→supportedProtocols
Published image tags mirror this — see Published artifacts.
OpenAPI and codegen
Contracts live under backend/openapi/streams/: core, inspect, diagnostics, kafka, kinesis. After changing YAML:
cd backend
mvn -pl eventore-api-codegen generate-sources
mvn -pl eventore-server -am package
Delegates are implemented under com.eventore.api.delegate in eventore-server. Inspect codegen maps domain types (TopicRef, ProtocolInspectCapabilities, …) — see backend/openapi/README.md.
Tests and CI
# Backend unit tests
cd backend && mvn test
# Integration tests (Docker required)
mvn test -DexcludedTestGroups= \
-pl eventore-provider-kafka,eventore-provider-rabbitmq,eventore-provider-mqtt,eventore-provider-pulsar,eventore-provider-jms -am
# Frontend
cd frontend && npm test && npm run test:e2e
CI workflow .github/workflows/publish-artifacts.yml runs unit tests, five-protocol Testcontainers suites, Vitest, Playwright smoke, MCP tests, and Helm lint before publishing images. Details: docs/TESTING.md.
Documentation site
npx serve docs -l 3456
After editing docs/seo/pages.json, run node docs/scripts/inject-seo.mjs from the repo root.