# 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 17 modules, runs 201 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                       | 17 |
| Unit tests                    | 201, all green |
| Real PBCs                     | 7 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`](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).