# vibe_erp — Project Progress

> Snapshot of where the framework stands today, what's done, and what's next.
> The detailed plan of record is
> [`docs/superpowers/specs/2026-04-07-vibe-erp-implementation-plan.md`](docs/superpowers/specs/2026-04-07-vibe-erp-implementation-plan.md).
> The architecture is locked in
> [`docs/superpowers/specs/2026-04-07-vibe-erp-architecture-design.md`](docs/superpowers/specs/2026-04-07-vibe-erp-architecture-design.md).

## At a glance

| | |
|---|---|
| **Latest version**             | v0.9 (post-P3.4) |
| **Latest commit**              | `feat(metadata): P3.4 — custom field application (Tier 1 customization)` |
| **Repo**                       | https://github.com/reporkey/vibe-erp |
| **Modules**                    | 13 |
| **Unit tests**                 | 129, all green |
| **End-to-end smoke runs**      | All cross-cutting services + all 3 PBCs verified against real Postgres; reference plug-in returns localised strings in 3 locales; Partner accepts custom-field `ext` declared in metadata |
| **Real PBCs implemented**      | 3 of 10 (`pbc-identity`, `pbc-catalog`, `pbc-partners`) |
| **Plug-ins serving HTTP**      | 1 (reference printing-shop, 7 endpoints + own DB schema + own metadata + own i18n bundles) |
| **Production-ready?**          | **No.** Foundation is solid; many capabilities still deferred. |

## Current stage

**Foundation complete; Tier 1 customization live; business surface area growing.** All eight cross-cutting platform services that PBCs and plug-ins depend on are live (auth, plug-in lifecycle, plug-in HTTP, plug-in linter, plug-in DB schemas, event bus + outbox, metadata loader, ICU4J translator). The metadata layer now drives **custom-field validation on JSONB `ext` columns** (P3.4), the cornerstone of the "key user adds fields without code" promise: a YAML declaration is enough to start enforcing types, scales, enums, and required-checks on every save. Three real PBCs (identity, catalog, partners) validate the modular-monolith template; Partner is the first to use custom fields. The reference printing-shop plug-in remains the executable acceptance test.

The next phase continues **building business surface area**: more PBCs (inventory, sales orders), the workflow engine (Flowable), permission enforcement against `metadata__role_permission`, and eventually the React SPA.

## Total scope (the v1.0 cut line)

The framework reaches v1.0 when, on a fresh Postgres, an operator can `docker run` the image, log in, drop a customer plug-in JAR into `./plugins/`, restart, and walk a real workflow end-to-end without writing any code — and the **same** image, against a different Postgres pointed at a different company, also serves a different customer with a different plug-in. See the implementation plan for the full v1.0 acceptance bar.

That target breaks down into roughly 30 work units across 8 phases. About **18 are done** as of today. Below is the full list with status.

### Phase 1 — Platform completion (foundation)

| # | Unit | Status |
|---|---|---|
| ~~P1.1~~ | ~~Postgres RLS transaction hook~~ | **N/A** — removed by single-tenant refactor |
| P1.2 | Plug-in linter (ASM bytecode scan) | ✅ DONE — `7af11f2` |
| P1.3 | Plug-in lifecycle: HTTP endpoints, DefaultPluginContext, dispatcher | ✅ DONE — `20d7ddc` |
| P1.4 | Plug-in Liquibase application + `PluginJdbc` | ✅ DONE — `7af11f2` |
| P1.5 | Metadata store seeding | ✅ DONE — `1ead32d` |
| P1.6 | ICU4J `Translator` implementation + locale resolution | ✅ DONE — `01c71a6` |
| P1.7 | Event bus + transactional outbox | ✅ DONE — `c2f2314` |
| P1.8 | JasperReports integration | 🔜 Pending |
| P1.9 | File store (local + S3) | 🔜 Pending |
| P1.10 | Job scheduler (Quartz) | 🔜 Pending |

### Phase 2 — Embedded workflow engine

| # | Unit | Status |
|---|---|---|
| P2.1 | Embedded Flowable (BPMN 2.0) + `TaskHandler` wiring | 🔜 Pending |
| P2.2 | BPMN designer (web) | 🔜 Pending — depends on R1 |
| P2.3 | User-task form rendering | 🔜 Pending |

### Phase 3 — Metadata store: forms and rules (Tier 1 customization)

| # | Unit | Status |
|---|---|---|
| P3.1 | JSON Schema form renderer (server) | 🔜 Pending |
| P3.2 | Form renderer (web) | 🔜 Pending — depends on R1 |
| P3.3 | Form designer (web) | 🔜 Pending — depends on R1 |
| P3.4 | Custom field application (JSONB `ext` validation) | ✅ DONE — `<this commit>` |
| P3.5 | Rules engine (event-driven) | 🔜 Pending |
| P3.6 | List view designer (web) | 🔜 Pending — depends on R1 |

### Phase 4 — Authentication and authorization

| # | Unit | Status |
|---|---|---|
| P4.1 | Built-in JWT auth + Argon2id + bootstrap admin | ✅ DONE — `540d916` |
| P4.2 | OIDC integration (Keycloak-compatible) | 🔜 Pending |
| P4.3 | Permission checking against `metadata__role_permission` | 🔜 Pending |

### Phase 5 — Core PBCs

| # | Unit | Status |
|---|---|---|
| P5.1 | `pbc-catalog` — items, units of measure | ✅ DONE — `69f3daa` |
| P5.2 | `pbc-partners` — customers, suppliers, contacts, addresses | ✅ DONE — `3e40cae` |
| P5.3 | `pbc-inventory` — stock items, lots, locations, movements | 🔜 Pending |
| P5.4 | `pbc-warehousing` — receipts, picks, transfers, counts | 🔜 Pending |
| P5.5 | `pbc-orders-sales` — quotes, sales orders, deliveries | 🔜 Pending |
| P5.6 | `pbc-orders-purchase` — RFQs, POs, receipts | 🔜 Pending |
| P5.7 | `pbc-production` — work orders, routings, operations | 🔜 Pending |
| P5.8 | `pbc-quality` — inspection plans, results, holds | 🔜 Pending |
| P5.9 | `pbc-finance` — GL, journal entries, AR/AP minimal | 🔜 Pending |

### Phase 6 — Web SPA (React + TS)

| # | Unit | Status |
|---|---|---|
| R1 | Vite + React + TS bootstrap, login flow, OpenAPI client | 🔜 Pending |
| R2 | Identity screens | 🔜 Pending |
| R3 | Customize / metadata UIs | 🔜 Pending |
| R4 | Per-PBC list/detail/create/edit screens | 🔜 Pending |

### Phase 7 — Reference printing-shop plug-in

| # | Unit | Status |
|---|---|---|
| REF.0 | Hello-world plug-in (PF4J + Plugin lifecycle + endpoints + own DB) | ✅ DONE through v0.6 |
| REF.1 | Real BPMN workflow handler (quote → job card) | 🔜 Pending — depends on P2.1 |
| REF.2 | Plate / ink / press CRUD as customer-style domain | ✅ Partial — plate + ink CRUD live (`7af11f2`) |
| REF.3 | Reference forms + automation rules in plug-in metadata | 🔜 Pending — depends on P3.3, P3.4 |

### Phase 8 — Hosted, AI agents, mobile (post-v1.0)

| # | Unit | Status |
|---|---|---|
| H1 | Instance provisioning console (one process per customer) | 🔜 Post-v1.0 |
| A1 | MCP server (REST endpoints exposed as AI-agent functions) | 🔜 v1.1 |
| M1 | React Native skeleton | 🔜 v2 |

## What's live right now

These are the cross-cutting platform services already wired into the running framework. Each was built with a real end-to-end smoke test against a Postgres container.

| Service | Module | What it does |
|---|---|---|
| **Auth** (P4.1) | `platform-security`, `pbc-identity` | Username/password login → HMAC-SHA256 JWT (15min access + 7d refresh). Bootstrap admin printed to logs on first boot. Spring Security filter chain enforces auth on every endpoint except `/actuator/health`, `/api/v1/_meta/**`, `/api/v1/auth/login`, `/api/v1/auth/refresh`. Principal bridges into the audit listener so `created_by` columns carry real user UUIDs. |
| **Plug-in HTTP** (P1.3) | `platform-plugins` | Plug-ins call `context.endpoints.register(method, path, handler)` to mount lambdas under `/api/v1/plugins/<plugin-id>/<path>`. Path templates with `{var}` extraction via Spring's `AntPathMatcher`. Plug-in code never imports Spring MVC types. |
| **Plug-in linter** (P1.2) | `platform-plugins` | At plug-in load time (before any plug-in code runs), ASM-walks every `.class` entry for references to `org.vibeerp.platform.*` or `org.vibeerp.pbc.*`. Forbidden references unload the plug-in with a per-class violation report. |
| **Plug-in DB schemas** (P1.4) | `platform-plugins` | Each plug-in ships its own `META-INF/vibe-erp/db/changelog.xml`. The host's `PluginLiquibaseRunner` applies it against the shared host datasource at plug-in start. Plug-ins query their own tables via the api.v1 `PluginJdbc` typed-SQL surface — no Spring or Hibernate types ever leak. |
| **Event bus + outbox** (P1.7) | `platform-events` | Synchronous in-process delivery PLUS a transactional outbox row in the same DB transaction. `Propagation.MANDATORY` so the bus refuses to publish outside an active transaction (no publish-and-rollback leaks). `OutboxPoller` flips PENDING → DISPATCHED every 5s. Wildcard `**` topic for the audit subscriber; topic-string and class-based subscribe. |
| **Metadata loader** (P1.5) | `platform-metadata` | Walks the host classpath and each plug-in JAR for `META-INF/vibe-erp/metadata/*.yml`, upserts entities/permissions/menus into `metadata__*` tables tagged by source. Idempotent (delete-by-source then insert). User-edited metadata (`source='user'`) is never touched. Public `GET /api/v1/_meta/metadata` returns the full set for SPA + AI-agent + OpenAPI introspection. |
| **i18n / Translator** (P1.6) | `platform-i18n` | ICU4J-backed `Translator` with named placeholders, plurals, gender, locale-aware number/date formatting. Per-plug-in instance scoped via a `(classLoader, baseName)` chain — plug-in's `META-INF/vibe-erp/i18n/messages_<locale>.properties` resolves before the host's `messages_<locale>.properties` for shared keys. `RequestLocaleProvider` reads `Accept-Language` from the active HTTP request via the servlet container, falling back to `vibeerp.i18n.defaultLocale` outside an HTTP context. JVM-default locale fallback explicitly disabled to prevent silent locale leaks. |
| **Custom field application** (P3.4) | `platform-metadata.customfield` | `CustomFieldRegistry` reads `metadata__custom_field` rows into an in-memory index keyed by entity name, refreshed at boot and after every plug-in load. `ExtJsonValidator` validates the JSONB `ext` map of any entity against the declared `FieldType`s — String maxLength, Integer/Decimal numeric coercion with precision/scale enforcement, Boolean, Date/DateTime ISO-8601 parsing, Enum allowed values, UUID format. Unknown keys are rejected; required missing fields are rejected; ALL violations are returned in a single 400 so a form submitter fixes everything in one round-trip. `Partner` is the first PBC entity to wire ext through `PartnerService.create/update`; the public `GET /api/v1/_meta/metadata/custom-fields/{entityName}` endpoint serves the api.v1 runtime view of declarations to the SPA / OpenAPI / AI agent. |
| **PBC pattern** (P5.x recipe) | `pbc-identity`, `pbc-catalog`, `pbc-partners` | Three real PBCs prove the recipe across three aggregate shapes (single-entity user, two-entity catalog, parent-with-children partners+addresses+contacts): domain entity extending `AuditedJpaEntity` → Spring Data JPA repository → application service → REST controller under `/api/v1/<pbc>/<resource>` → cross-PBC facade in `api.v1.ext.<pbc>` → adapter implementation. Architecture rule enforced by the Gradle build: PBCs never import each other, never import `platform-bootstrap`. |

## What the reference plug-in proves end-to-end

The printing-shop reference plug-in is the framework's executable acceptance test. As of `1ead32d` it demonstrates **everything a real customer plug-in needs** except workflow handling:

```
Plug-in JAR drop → host bootstrap:
  1. PF4J discovers the JAR and reads plugin.yml
  2. PluginLinter ASM-walks every class — passes
  3. PluginLiquibaseRunner applies META-INF/vibe-erp/db/changelog.xml
     → creates plugin_printingshop__plate, plugin_printingshop__ink_recipe
  4. MetadataLoader.loadFromPluginJar reads
     META-INF/vibe-erp/metadata/printing-shop.yml
     → 2 entities, 5 permissions, 2 menus tagged source='plugin:printing-shop'
  5. VibeErpPluginManager calls Plugin.start(context) with a real
     PluginContext (logger + endpoints + eventBus + jdbc all wired)
  6. The plug-in's start() lambda registers 7 HTTP endpoints
  7. Boot completes, app is serving traffic

Live HTTP traffic:
  POST /api/v1/auth/login (admin)                    → 200, JWT
  POST /api/v1/plugins/printing-shop/plates (Bearer) → 201, plate created
  GET  /api/v1/plugins/printing-shop/plates          → list of plates
  GET  /api/v1/plugins/printing-shop/plates/{id}     → fetch by id
  POST /api/v1/plugins/printing-shop/inks            → 201, ink created
  GET  /api/v1/_meta/metadata                        → all 6 entities + 18 permissions
  GET  /api/v1/identity/users (Bearer)               → still works
  GET  /api/v1/catalog/uoms (Bearer)                 → 15 seeded UoMs
```

This is **real**: a JAR file dropped into a directory, loaded by the framework, executing customer-specific business logic against its own database tables, exposed via REST. The plug-in code never imports a single internal framework class — and the linter would refuse to load it if it tried.

## What's not yet live (the deferred list)

- **Workflow engine.** No Flowable yet. The api.v1 `TaskHandler` interface exists; the runtime that calls it doesn't.
- **Forms.** No JSON Schema form renderer (server or client). No form designer.
- **Reports.** No JasperReports.
- **File store.** No abstraction; no S3 backend.
- **Job scheduler.** No Quartz. Periodic jobs don't have a home.
- **OIDC.** Built-in JWT only. OIDC client (Keycloak-compatible) is P4.2.
- **Permission checks.** `Principal` is bound; `metadata__permission` is seeded; the actual `@RequirePermission` enforcement layer is P4.3.
- **More PBCs.** Identity, catalog and partners exist. Inventory, warehousing, orders, production, quality, finance are all pending.
- **Web SPA.** No React app. The framework is API-only today.
- **MCP server.** The architecture leaves room for it; the implementation is v1.1.
- **Mobile.** v2.

## How to run what exists today

```bash
# Bring up Postgres + the plug-in JAR (in background)
docker compose up -d db
./gradlew :reference-customer:plugin-printing-shop:installToDev

# Boot the framework against it
./gradlew :distribution:bootRun

# In another shell:
curl -s localhost:8080/api/v1/_meta/info
curl -s localhost:8080/api/v1/_meta/metadata | jq

# Read the bootstrap admin password from the boot logs, then:
ACCESS=$(curl -s -H 'Content-Type: application/json' \
  -X POST localhost:8080/api/v1/auth/login \
  -d '{"username":"admin","password":"<from-logs>"}' | jq -r .accessToken)

curl -s -H "Authorization: Bearer $ACCESS" localhost:8080/api/v1/identity/users
curl -s -H "Authorization: Bearer $ACCESS" localhost:8080/api/v1/catalog/uoms
curl -s -H "Authorization: Bearer $ACCESS" localhost:8080/api/v1/plugins/printing-shop/plates
```

## Module map

```
api/api-v1                    PUBLIC CONTRACT — semver-governed
platform/platform-bootstrap   Spring Boot main, props, web filters
platform/platform-persistence Audit base, JPA entities, PrincipalContext
platform/platform-security    JWT issuer/verifier, Spring Security config, password encoder
platform/platform-events      EventBus impl, transactional outbox, poller
platform/platform-metadata    MetadataLoader, MetadataController
platform/platform-i18n        IcuTranslator, RequestLocaleProvider (P1.6)
platform/platform-plugins     PF4J host, linter, Liquibase runner, endpoint dispatcher, PluginJdbc

pbc/pbc-identity              User entity end-to-end + auth + bootstrap admin
pbc/pbc-catalog               Item + Uom entities + cross-PBC CatalogApi facade
pbc/pbc-partners              Partner + Address + Contact entities + cross-PBC PartnersApi facade

reference-customer/plugin-printing-shop
                              Reference plug-in: own DB schema (plate, ink_recipe),
                              own REST endpoints, own metadata YAML

distribution                  Bootable Spring Boot fat-jar assembly
```

13 Gradle subprojects. Architectural dependency rule (PBCs never import each other; plug-ins only see api.v1) is enforced by the root `build.gradle.kts` at configuration time.

## Where to look next

- **Detailed roadmap:** [`docs/superpowers/specs/2026-04-07-vibe-erp-implementation-plan.md`](docs/superpowers/specs/2026-04-07-vibe-erp-implementation-plan.md) — every unit, every dependency, every acceptance test.
- **Architecture rationale:** [`docs/superpowers/specs/2026-04-07-vibe-erp-architecture-design.md`](docs/superpowers/specs/2026-04-07-vibe-erp-architecture-design.md) — 14 sections, validated against 2026 ERP/EBC SOTA.
- **Project guardrails:** [`CLAUDE.md`](CLAUDE.md) — the 11 rules every change is held to.
- **Git history:** every chunk is one commit with a detailed message describing what landed, what was deferred, and any bug caught by the smoke test.