README.md
vibe_erp
vibe_erp is an ERP/EBC framework for the printing industry, sold worldwide and deployed self-hosted-first. It is not an ERP application: it is the substrate on which any printing shop's workflows, forms, roles, and rules can be assembled by configuration and plug-ins instead of by forking the core. The reference business under raw/ is one example customer, used as an executable acceptance test, never as the spec.
Why a framework, not an app
Printing shops differ in process, terminology, paperwork, and order of operations. An app that hard-codes one shop's workflow becomes a fork farm the moment a second customer signs up. vibe_erp follows the Clean Core philosophy borrowed from SAP S/4HANA: the core stays generic and upgrade-safe, and every customer-specific concept lives in metadata rows or plug-ins. The core never knows what a "plate" or a "press" is — those concepts are introduced by a plug-in. Upgrading the core does not touch the customer's extensions.
Architecture in one picture
┌──────────────────────────────────────────────────────────────────────┐
│ Customer's network │
│ │
│ Browser (React SPA) ─┐ │
│ AI agent (MCP, v1.1)─┼─► Reverse proxy ──► vibe_erp backend (1 image)│
│ 3rd-party system ─┘ │ │
│ │ │
│ Inside the image (one Spring Boot process): │ │
│ ┌─────────────────────────────────────┐ │ │
│ │ HTTP layer (REST + OpenAPI + MCP) │ │ │
│ ├─────────────────────────────────────┤ │ │
│ │ Public Plug-in API (api.v1.*) │◄──┤ loaded from │
│ │ — the only stable contract │ │ ./plugins/*.jar │
│ ├─────────────────────────────────────┤ │ via PF4J │
│ │ Core PBCs (modular monolith): │ │ │
│ │ identity · catalog · partners · │ │ │
│ │ inventory · warehousing · │ │ │
│ │ orders-sales · orders-purchase · │ │ │
│ │ production · quality · finance │ │ │
│ ├─────────────────────────────────────┤ │ │
│ │ Cross-cutting: │ │ │
│ │ • Flowable (workflows-as-data) │ │ │
│ │ • Metadata store (Doctype-style) │ │ │
│ │ • i18n (ICU MessageFormat) │ │ │
│ │ • Reporting (JasperReports) │ │ │
│ │ • Job scheduler (Quartz) │ │ │
│ │ • Audit, security, events │ │ │
│ └─────────────────────────────────────┘ │ │
│ ▼ │
│ PostgreSQL (mandatory) │
│ File store (local or S3) │
└──────────────────────────────────────────────────────────────────────┘
Optional sidecars for larger deployments (off by default):
• Keycloak (OIDC) • Redis (cache + queue)
• OpenSearch (search) • SMTP relay
The full architecture lives at docs/superpowers/specs/2026-04-07-vibe-erp-architecture-design.md.
Stack
- Kotlin on the JVM, Spring Boot, single fat-JAR / single Docker image
- PostgreSQL (the only mandatory external dependency)
- Embedded Flowable (BPMN 2.0) for workflows-as-data
- PF4J + Spring Boot child contexts for plug-in classloader isolation
- ICU4J + Spring
MessageSourcefor i18n - JasperReports for reporting
- React + TypeScript SPA for the web client
Repository layout
vibe-erp/
├── api/
│ └── api-v1/ ← THE CONTRACT (semver, published to Maven Central)
├── platform/ ← Framework runtime (internal)
├── pbc/ ← Core PBCs (one Gradle subproject each)
├── reference-customer/
│ └── plugin-printing-shop/ ← Reference plug-in, built and CI-tested, not loaded by default
├── web/ ← React + TypeScript SPA
├── docs/ ← Framework documentation
└── distribution/ ← Bootable assembly: fat JAR + Docker image
Building
# Build everything (compiles 13 modules, runs 118 unit tests)
./gradlew build
# Bring up Postgres + the reference plug-in JAR
docker compose up -d db
./gradlew :reference-customer:plugin-printing-shop:installToDev
# Boot the framework against it
./gradlew :distribution:bootRun
The bootstrap admin password is printed to the application logs on first boot. After login, REST endpoints are live under /api/v1/identity/users, /api/v1/catalog/uoms, /api/v1/catalog/items, /api/v1/partners/partners, /api/v1/plugins/printing-shop/*, and the public introspection endpoint at /api/v1/_meta/metadata.
Status
Current stage: foundation complete; business surface area growing; i18n online. All eight cross-cutting platform services are live and verified end-to-end against a real Postgres: auth (JWT + Argon2id + bootstrap admin), plug-in HTTP endpoints, plug-in linter (ASM bytecode scan), plug-in-owned DB schemas + typed SQL, event bus + transactional outbox, the metadata seeder, and the ICU4J translator with per-plug-in locale chain. Three real PBCs (identity + catalog + partners) validate the modular-monolith template across three different aggregate shapes. The reference printing-shop plug-in is the executable acceptance test: it owns its own DB schema, CRUDs its own domain via REST, ships its own message bundles, returns localised strings in three locales, and would be rejected at install time if it tried to import any internal framework class.
| Modules | 13 |
| Unit tests | 118, all green |
| Real PBCs | 3 of 10 |
| Cross-cutting services live | 8 |
| Plug-ins serving HTTP | 1 (reference printing-shop) |
| Production-ready | No — workflow engine, forms, web SPA, more PBCs all still pending |
For the full feature inventory, completed work, and next-priority list, see PROGRESS.md. For the detailed roadmap, see docs/superpowers/specs/2026-04-07-vibe-erp-implementation-plan.md.
Documentation
- Documentation index
- Architecture overview
- Plug-in API overview
- Plug-in author getting started
- Workflow authoring guide
- Form authoring guide
- i18n guide
- Customer onboarding guide
License
Apache License 2.0. See LICENSE.