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 18 modules, runs 230 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; Tier 1 customization live; business surface area growing. 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 + custom-field validator, and the ICU4J translator with per-plug-in locale chain. The Tier 1 customization story works end-to-end: a YAML declaration adds a typed custom field to an existing entity, the framework's ExtJsonValidator enforces it on every save, and the SPA-facing GET /api/v1/_meta/metadata/custom-fields/{entityName} endpoint serves the runtime view to the form builder.
| Modules | 18 |
| Unit tests | 230, all green |
| Real PBCs | 8 of 10 |
| Cross-cutting services live | 9 |
| 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.