朱子纯 / vibe-erp

README.md 6.79 KB

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 MessageSource for 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

This is a v0.1 skeleton. Not all modules ship yet — expect commands below to work for the modules that exist and to be no-ops or stubs for the rest.

# Build everything that currently exists
./gradlew build

# Run the bootable distribution against a local Postgres
./gradlew :distribution:bootRun

# Or bring everything (Postgres + vibe_erp) up with Docker
docker compose up

Status

v0.1 — buildable skeleton, one PBC implemented end-to-end (pbc-identity), plug-in loading proven with a hello-world reference plug-in. Not production. See docs/superpowers/specs/2026-04-07-vibe-erp-architecture-design.md for the full v1.0 plan.

Documentation

License

Apache License 2.0. See LICENSE.