# 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`](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

```bash
# 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`](PROGRESS.md). For the detailed roadmap, see [`docs/superpowers/specs/2026-04-07-vibe-erp-implementation-plan.md`](docs/superpowers/specs/2026-04-07-vibe-erp-implementation-plan.md).

## Documentation

- [Documentation index](docs/index.md)
- [Architecture overview](docs/architecture/overview.md)
- [Plug-in API overview](docs/plugin-api/overview.md)
- [Plug-in author getting started](docs/plugin-author/getting-started.md)
- [Workflow authoring guide](docs/workflow-authoring/guide.md)
- [Form authoring guide](docs/form-authoring/guide.md)
- [i18n guide](docs/i18n/guide.md)
- [Customer onboarding guide](docs/customer-onboarding/guide.md)

## License

Apache License 2.0. See [`LICENSE`](LICENSE).