EERP Developer Documentation¶

EERP is an open-source, modular ERP framework built around three principles: type safety without runtime cost, modular extensibility via a hybrid WASM/Go model, and ERP-domain defaults baked into every layer.

This documentation is written for developers joining the project. It explains not just what the code does, but why it was built this way.

Our graphify : graphify-eerp

What EERP is¶

EERP is a framework, not an application. Its job is to provide a runtime and a set of contracts against which independent ERP modules (inventory, CRM, accounting, HR, etc.) are developed and loaded.

EERP uses a hybrid module model:

WASM component (Rust or any WASM-capable language): responsible only for declaring the module's database schema via the migrate() ABI. Runs inside a Wasmtime sandbox at startup.
Go service (monolith): implements all business logic, directly compiled into the core binary. Uses the ORM and is wired into the HTTP server.

This split gives you schema isolation and sandboxing at startup, and maximum performance at request time.

Current state: all shipped modules (CRM, etc.) run as pure Go services. The WASM migration protocol is implemented and active in the loader; Rust-compiled .wasm binaries are the next step for full schema decoupling.

graph TD
    subgraph "Core Runtime (Go)"
        DB[(PostgreSQL)]
        ORM[ORM Layer]
        ML[Module Loader]
        HTTP[HTTP Server]
        CONFIG[Configuration]
    end

    subgraph "Go Services (monolith — business logic)"
        CRM_S[CRM Service]
        INV_S[Inventory Service]
        ACC_S[Accounting Service]
    end

    subgraph "WASM Modules (schema protocol — Rust)"
        CRM_W[crm.wasm]
        INV_W[inventory.wasm]
        ACC_W[accounting.wasm]
    end

    subgraph Frontend
        FE[Next.js Front Server<br/>React + Zustand]
    end

    FE -->|REST / JSON| HTTP
    HTTP --> CRM_S
    HTTP --> INV_S
    CRM_S --> ORM
    ORM --> DB
    ML -->|migrate ABI at startup| CRM_W
    ML -->|migrate ABI at startup| INV_W
    ML -->|migrate ABI at startup| ACC_W
    CRM_W -->|schema declaration| DB
    INV_W -->|schema declaration| DB

Stack at a Glance¶

Layer	Technology	Why
Backend	Go 1.26	Static binaries, excellent concurrency, strong type system
ORM	Custom (pgx v5)	Zero reflection at query time, ERP-specific features
Module schema	Rust → WASM (Wasmtime)	Sandboxed schema declaration, language-agnostic migrate() ABI
Module logic	Go (monolith)	Zero IPC overhead, full ORM access, single binary deploy
Database	PostgreSQL 18	Mature, feature-rich, excellent Go driver ecosystem
Frontend	React + Next.js (App Router) + TypeScript	Largest ecosystem and talent pool; runs on a dedicated front server (BFF)
Frontend state	Zustand	Selector-based subscriptions avoid React Context re-render cascades; ~1 KB

Documentation Map¶

If you want to…	Start here
Run the project for the first time	Getting Started
Understand how all the pieces fit	Architecture Overview
Work with the database	ORM · Database Layer
Build a module (WASM/Rust path)	Creating a WASM Module
Build a module (Go monolith path)	Creating a Go Module
Understand the frontend	Frontend Overview · View Engine
Add a frontend view to a module	Creating a Frontend Module
Add a new data entity	Creating an Entity
Write tests	Testing
Understand a design decision	ADRs

Repository Layout¶

eerp/
├── core/                    # Go backend
│   ├── cmd/app/main.go      # Entry point — wires DB, WASM loader, Go services
│   ├── orm/                 # Custom ORM (public API)
│   ├── internal/
│   │   ├── module/          # Hybrid module loader (WASM migrate ABI + Go service init)
│   │   │   ├── detector.go  # Filesystem scan, dependency resolution, priority assignment
│   │   │   ├── load.go      # Wasmtime instantiation, migrate() call, DDL application
│   │   │   ├── migration.go # applyMigration — executes ALTER TABLE via pgx
│   │   │   └── snapshot.go  # Change detection cache
│   │   ├── types/           # Shared types (Config, Module, Migration, Operation)
│   │   └── common/          # Logger, file utilities, dependency resolver
│   └── modules/
│       └── crm/             # CRM module — Go service (monolith business logic)
│           └── internal/
│               └── crm.go   # Contact entity + Service (Create/List/Update/Delete)
├── core-front/              # Next.js front server (React + Zustand) — pnpm workspace
│   ├── packages/core-front/ # @eerp/core-front engine (the frontend ABI):
│   │   └── src/             #   api (ApiClient/BFF), views (descriptors, stores, renderers),
│   │                        #   auth (permissions, guards), registry (FrontModule)
│   └── apps/shell/          # Next.js App Router host service
│       ├── app/             #   routes: layout, login, api/auth (BFF), [...module] catch-all
│       └── src/             #   server session/ApiClient + generated module manifest (gitignored)
├── compose.yml              # PostgreSQL dev environment
├── eerp-config.json         # Runtime configuration (module_root, DB, pool)
└── Makefile                 # Developer commands