From 3f5831a22eec5e9db52abac3230d667c50297941 Mon Sep 17 00:00:00 2001 From: AIRONAX Developer Date: Tue, 13 Oct 2026 01:04:43 +0530 Subject: [PATCH 1/2] README updated alpha verison --- README.md | 54 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 38 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 19ad1e2b..c1bd5793 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,9 @@ **Modular open-source ERP/CRM platform** - Go backend, PostgreSQL, installable apps, and a TypeScript workspace client for enterprise operations. [![CI](https://github.com/ProjectMeru/sumeru/actions/workflows/ci.yml/badge.svg)](https://github.com/ProjectMeru/sumeru/actions/workflows/ci.yml) -[![Go](https://img.shields.io/badge/Go-1.26.6+-00ADD8?logo=go&logoColor=white)](https://go.dev/dl/) +[![Go](https://img.shields.io/badge/Go-1.26.9+-00ADD8?logo=go&logoColor=white)](https://go.dev/dl/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) -[![Pre-Alpha](https://img.shields.io/badge/Status-Pre--Alpha-critical)](https://github.com/ProjectMeru/sumeru) +[![Alpha]()](https://github.com/ProjectMeru/sumeru) [![Docs](https://img.shields.io/badge/Docs-projectmeru.github.io-informational)](https://projectmeru.github.io/sumeru/docs/) ## Table of contents @@ -13,6 +13,7 @@ - [Sumeru](#sumeru) - [Table of contents](#table-of-contents) - [Overview](#overview) + - [Platform maturity](#platform-maturity) - [Features](#features) - [Preview](#preview) - [Architecture](#architecture) @@ -31,26 +32,47 @@ Sumeru is a **modular ERP and CRM engine** for teams that want a single deployable stack: **PostgreSQL** for data, **XML views** for screens and menus, **Go models** for business logic, and a **SWC** web workspace for list, form, kanban, and analysis work. Install **apps** (addons) from disk; extend behavior through manifests and the **`sumeru/core/sdk`** surface instead of forking core. -This repository (`module sumeru`) is the **kernel**: ORM, HTTP/RPC, rendering shell, and base apps (`base`, `mail`, …). Standard CRM/ERP apps ship in **[sumeru_addons](https://github.com/ProjectMeru/sumeru_addons)**. Most integrators run the server from **[sumeru_custom_addons](https://github.com/ProjectMeru/sumeru_custom_addons)** (paths, config, generated imports). +This repository (`module sumeru`) is the **kernel**: ORM, HTTP/JSON-RPC, rendering shell, and platform apps (`base`, `platform`, `mail`, `currency`, …). Standard CRM/ERP apps ship in **[sumeru_addons](https://github.com/ProjectMeru/sumeru_addons)**. Most integrators run the server from **[sumeru_custom_addons](https://github.com/ProjectMeru/sumeru_custom_addons)** (paths, config, generated imports). > [!CAUTION] > -> **Pre-alpha software** — not for production or regulated workloads. +> **Alpha — platform kernel** — not for production or regulated workloads. > -> - APIs, schemas, and UX may change without notice. -> - Use for local development, evaluation, and feedback only. +> - The **platform layer** (ORM, security, workspace, mail/bus, automation) is usable for **development, demos, and custom modules**. +> - Schemas, RPC payloads, and UX may still change between releases. +> - Business app depth and operational hardening live in sibling repos and your deployment process. + +## Platform maturity + +Status reflects **this repository only** (engine + kernel addons), not full ERP product parity in **sumeru_addons**. + +| Area | Status | Notes | +| ------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- | +| Modules & ORM | **Ready** | Manifests, install/update, compute, domains, multi-company, elevated context | +| Security | **Ready** | Groups, record rules, model ACL, field ACL UI | +| Views & SWC | **Ready** | List, form, kanban, graph, pivot, calendar, gantt, map, cohort, hierarchy, activity; view inherit | +| JSON-RPC | **Ready** | `POST /api/rpc` with session or API key — **the supported integration surface** (no separate REST layer planned) | +| Reports, import/export | **Ready** | Document reports; import wizard; async export / bulk jobs | +| Mail & activities | **Partial** | Messages, followers, notifications, outbound mail queue, activity board; no inbound IMAP gateway | +| Realtime | **Ready** | Bus channels, durable events, client reconnect | +| Portal | **Partial** | Portal shell and share links; not a full customer portal product | +| Auth | **Ready** | Password login, OAuth/OIDC providers, TOTP, trusted device | +| Automation | **Ready** | Cron, server actions, workflow hooks (`automation` addon) | +| Currency, UoM, properties | **Ready** | Dedicated addons; monetary fields; JSONB properties + definition admin | + +Integrations should use **JSON-RPC** (`/api/rpc`) and documented HTTP routes (content, export, health). A resource-oriented REST API is **not** on the roadmap. ## Features -| Area | Capabilities | -| ------------------ | ---------------------------------------------------------------------------------- | -| **Apps & modules** | Manifests, dependency order, install/update from `addons_path`; XML data and views | -| **Data layer** | PostgreSQL ORM, model sync on startup, record rules, multi-company | -| **Workspace** | List, form, kanban, graph, pivot, calendar, gantt, map, cohort | -| **Collection UX** | Search, filters, group-by, custom domains, saved-search favorites | -| **Integrations** | `POST /api/rpc` (session or API key); mail/chatter; export/import hooks | -| **Client** | TypeScript SWC in `core/swc/`; server-rendered shell + SPA workspace | -| **Extensibility** | Prefer **`sumeru/core/sdk`** for addons; `sum-*` design tokens in CSS | +| Area | Capabilities | +| ------------------ | ---------------------------------------------------------------------------------------- | +| **Apps & modules** | Manifests, dependency order, install/update from `addons_path`; XML data and views | +| **Data layer** | PostgreSQL ORM, model sync on startup, record rules, multi-company | +| **Workspace** | List, form, kanban, graph, pivot, calendar, gantt, map, cohort, hierarchy, activity | +| **Collection UX** | Search, filters, group-by, custom domains, saved-search favorites, command palette | +| **Integrations** | **JSON-RPC** `POST /api/rpc` (session or API key); mail and notifications; import/export | +| **Client** | TypeScript SWC in `core/swc/`; server-rendered shell + SPA workspace | +| **Extensibility** | Prefer **`sumeru/core/sdk`** for addons; `sum-*` design tokens in CSS | ## Preview @@ -94,7 +116,7 @@ Full layer diagram and request flow: **[docs/architecture-layers.md](docs/archit ### Prerequisites -- [Go 1.26.6+](https://go.dev/dl/) +- [Go 1.26.9+](https://go.dev/dl/) - [Node.js](https://nodejs.org/) (npm — builds SWC bundles; not committed to git) - [PostgreSQL](https://www.postgresql.org/) - Git From c89ecccca48ce58011e6408aaa8f473d24318924 Mon Sep 17 00:00:00 2001 From: AIRONAX Developer Date: Tue, 13 Oct 2026 01:09:26 +0530 Subject: [PATCH 2/2] docs updated --- README.md | 202 +++++------------------------------- docs/architecture-layers.md | 152 ++++++++++----------------- docs/ddl-policy.md | 24 ++--- docs/ha-ops.md | 27 ++--- docs/ops-runbook.md | 40 ++++--- docs/platform-status.md | 48 +++++++++ docs/sso.md | 45 ++++++-- 7 files changed, 217 insertions(+), 321 deletions(-) create mode 100644 docs/platform-status.md diff --git a/README.md b/README.md index c1bd5793..268068ea 100644 --- a/README.md +++ b/README.md @@ -1,130 +1,23 @@ # Sumeru -**Modular open-source ERP/CRM platform** - Go backend, PostgreSQL, installable apps, and a TypeScript workspace client for enterprise operations. +**Modular open-source ERP/CRM platform** — Go backend, PostgreSQL, installable apps, and a TypeScript workspace client. [![CI](https://github.com/ProjectMeru/sumeru/actions/workflows/ci.yml/badge.svg)](https://github.com/ProjectMeru/sumeru/actions/workflows/ci.yml) [![Go](https://img.shields.io/badge/Go-1.26.9+-00ADD8?logo=go&logoColor=white)](https://go.dev/dl/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) -[![Alpha]()](https://github.com/ProjectMeru/sumeru) +[![Alpha](https://img.shields.io/badge/Status-Alpha%20(platform%20kernel)-orange)](https://github.com/ProjectMeru/sumeru) [![Docs](https://img.shields.io/badge/Docs-projectmeru.github.io-informational)](https://projectmeru.github.io/sumeru/docs/) -## Table of contents - -- [Sumeru](#sumeru) - - [Table of contents](#table-of-contents) - - [Overview](#overview) - - [Platform maturity](#platform-maturity) - - [Features](#features) - - [Preview](#preview) - - [Architecture](#architecture) - - [Repository ecosystem](#repository-ecosystem) - - [Getting started](#getting-started) - - [Prerequisites](#prerequisites) - - [Recommended — custom workspace](#recommended--custom-workspace) - - [Alternative — core only](#alternative--core-only) - - [First run](#first-run) - - [Configuration](#configuration) - - [Development](#development) - - [Documentation](#documentation) - - [Community](#community) - ## Overview -Sumeru is a **modular ERP and CRM engine** for teams that want a single deployable stack: **PostgreSQL** for data, **XML views** for screens and menus, **Go models** for business logic, and a **SWC** web workspace for list, form, kanban, and analysis work. Install **apps** (addons) from disk; extend behavior through manifests and the **`sumeru/core/sdk`** surface instead of forking core. - -This repository (`module sumeru`) is the **kernel**: ORM, HTTP/JSON-RPC, rendering shell, and platform apps (`base`, `platform`, `mail`, `currency`, …). Standard CRM/ERP apps ship in **[sumeru_addons](https://github.com/ProjectMeru/sumeru_addons)**. Most integrators run the server from **[sumeru_custom_addons](https://github.com/ProjectMeru/sumeru_custom_addons)** (paths, config, generated imports). +Sumeru is a **modular ERP/CRM engine**: **PostgreSQL**, **XML views**, **Go models** (`sumeru/core/sdk`), and the **SWC** web workspace. This repo is the **kernel** (ORM, JSON-RPC, shell, platform apps). Standard apps ship in **[sumeru_addons](https://github.com/ProjectMeru/sumeru_addons)**; most teams run from **[sumeru_custom_addons](https://github.com/ProjectMeru/sumeru_custom_addons)**. > [!CAUTION] -> -> **Alpha — platform kernel** — not for production or regulated workloads. -> -> - The **platform layer** (ORM, security, workspace, mail/bus, automation) is usable for **development, demos, and custom modules**. -> - Schemas, RPC payloads, and UX may still change between releases. -> - Business app depth and operational hardening live in sibling repos and your deployment process. - -## Platform maturity - -Status reflects **this repository only** (engine + kernel addons), not full ERP product parity in **sumeru_addons**. - -| Area | Status | Notes | -| ------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------- | -| Modules & ORM | **Ready** | Manifests, install/update, compute, domains, multi-company, elevated context | -| Security | **Ready** | Groups, record rules, model ACL, field ACL UI | -| Views & SWC | **Ready** | List, form, kanban, graph, pivot, calendar, gantt, map, cohort, hierarchy, activity; view inherit | -| JSON-RPC | **Ready** | `POST /api/rpc` with session or API key — **the supported integration surface** (no separate REST layer planned) | -| Reports, import/export | **Ready** | Document reports; import wizard; async export / bulk jobs | -| Mail & activities | **Partial** | Messages, followers, notifications, outbound mail queue, activity board; no inbound IMAP gateway | -| Realtime | **Ready** | Bus channels, durable events, client reconnect | -| Portal | **Partial** | Portal shell and share links; not a full customer portal product | -| Auth | **Ready** | Password login, OAuth/OIDC providers, TOTP, trusted device | -| Automation | **Ready** | Cron, server actions, workflow hooks (`automation` addon) | -| Currency, UoM, properties | **Ready** | Dedicated addons; monetary fields; JSONB properties + definition admin | - -Integrations should use **JSON-RPC** (`/api/rpc`) and documented HTTP routes (content, export, health). A resource-oriented REST API is **not** on the roadmap. - -## Features - -| Area | Capabilities | -| ------------------ | ---------------------------------------------------------------------------------------- | -| **Apps & modules** | Manifests, dependency order, install/update from `addons_path`; XML data and views | -| **Data layer** | PostgreSQL ORM, model sync on startup, record rules, multi-company | -| **Workspace** | List, form, kanban, graph, pivot, calendar, gantt, map, cohort, hierarchy, activity | -| **Collection UX** | Search, filters, group-by, custom domains, saved-search favorites, command palette | -| **Integrations** | **JSON-RPC** `POST /api/rpc` (session or API key); mail and notifications; import/export | -| **Client** | TypeScript SWC in `core/swc/`; server-rendered shell + SPA workspace | -| **Extensibility** | Prefer **`sumeru/core/sdk`** for addons; `sum-*` design tokens in CSS | - -## Preview - -User flow: **sign in → apps catalog → settings and workspace**. - -**Sign-in** — enterprise login shell with optional company logo and tagline on the left panel. - -![Enterprise login with branding panel](core/engine/assets/img/screenshots/login_screen.png) - -**Apps** — browse, install, and open CRM/ERP modules from the catalog. - -![Installed and available apps](core/engine/assets/img/screenshots/apps_imgs.png) - -**Settings & workspace** — configure the organization and work in list, form, and analysis views. - -![Settings hub and workspace chrome](core/engine/assets/img/screenshots/hero_img.png) - -## Architecture - -Sumeru runs as a **Go monolith**: HTTP handlers and JSON-RPC call into the ORM; addons register models and actions; the SWC client loads inside an HTML shell from `core/engine/render`. - -| Layer | Location | -| -------------------- | ----------------------------------------------- | -| UI shell & routes | `core/server/web`, `core/engine/render` | -| Workspace client | `core/swc` | -| Business logic & RPC | `core/server/api`, `core/orm`, `core/sdk` | -| Modules | `core/module`, `addons/`, external addon repos | -| Security | Access CSV/XML, record rules, groups, field ACL | - -Full layer diagram and request flow: **[docs/architecture-layers.md](docs/architecture-layers.md)**. - -## Repository ecosystem - -| Repository | Role | -| ------------------------------------------------------------------------------- | ------------------------------------------------------- | -| **[sumeru](https://github.com/ProjectMeru/sumeru)** | Core engine + kernel apps | -| **[sumeru_addons](https://github.com/ProjectMeru/sumeru_addons)** | Standard CRM/ERP apps | -| **[sumeru_custom_addons](https://github.com/ProjectMeru/sumeru_custom_addons)** | Workspace: `sumeru.conf`, generated imports, `make run` | - -## Getting started - -### Prerequisites +> **Alpha (platform kernel)** — not for production or regulated use. See **[docs/platform-status.md](docs/platform-status.md)** for what is ready, partial, or on the roadmap (integrations are **JSON-RPC** only). -- [Go 1.26.9+](https://go.dev/dl/) -- [Node.js](https://nodejs.org/) (npm — builds SWC bundles; not committed to git) -- [PostgreSQL](https://www.postgresql.org/) -- Git -- Optional: Docker for `make test-integration` +## Quick start -### Recommended — custom workspace - -Clone the three sibling repositories, create a database matching `db_name`, then run from the workspace repo: +**Prerequisites:** Go 1.26.9+, Node.js (SWC build), PostgreSQL. ```bash mkdir -p ~/sumeru_erp && cd ~/sumeru_erp @@ -132,84 +25,37 @@ git clone git@github.com:ProjectMeru/sumeru.git git clone git@github.com:ProjectMeru/sumeru_addons.git git clone git@github.com:ProjectMeru/sumeru_custom_addons.git -# psql -c "CREATE DATABASE sumeru;" - cd sumeru_custom_addons -cp sumeru.conf.example sumeru.conf # edit db_*, http_port, addons_path -make setup && make run -``` - -Open **`http://localhost:8080`** (or your `http_port`). Details: [sumeru_custom_addons README](https://github.com/ProjectMeru/sumeru_custom_addons/blob/main/README.md). - -### Alternative — core only - -Kernel apps under `sumeru/addons/`: - -```bash -cd sumeru -cp sumeru.conf.example sumeru.conf # addons_path = addons +cp sumeru.conf.example sumeru.conf # db_*, http_port, addons_path make setup && make run ``` -Optional sample data: +Open `http://localhost:8080`. Empty DB → **`/setup`**; then **`/web/login`** → **`/web/apps`**. Workspace details: [sumeru_custom_addons README](https://github.com/ProjectMeru/sumeru_custom_addons/blob/main/README.md). -```bash -go run ./cmd/sumeru -- -c sumeru.conf -i company,user --stop-after-init -make run -``` - -### First run +**Core only:** `cd sumeru && cp sumeru.conf.example sumeru.conf && make setup && make run` (`addons_path = addons`). -| Step | Behavior | -| ----------- | ---------------------------------------------------------------------------------------------- | -| Empty DB | Browser **`/setup`** wizard (company + admin); see `setup_*` keys in **`sumeru.conf.example`** | -| After setup | **`/web/login`**; set **`dev_mode = true`** for local UI iteration | -| Signed in | `/` → **`/web/apps`** | - -## Configuration +## Preview -Copy **`sumeru.conf.example`** → **`sumeru.conf`** next to `go.mod` (or in `sumeru_custom_addons` for the workspace flow). +![Login](core/engine/assets/img/screenshots/login_screen.png) -| Setting | Required | Notes | -| ---------------------------- | -------- | --------------------------------- | -| `db_*`, `db_sslmode` | Yes | PostgreSQL connection | -| `http_port` | Yes | Default `8080` | -| `addons_path` | Yes | Comma-separated addon directories | -| `dev_mode` | No | `true` for local development | -| `log_enabled` / `log_stdout` | No | See example for file logging | +![Apps catalog](core/engine/assets/img/screenshots/apps_imgs.png) -Reference: [configuration guide](https://projectmeru.github.io/sumeru/docs/guides/start/configuration.html). +![Workspace](core/engine/assets/img/screenshots/hero_img.png) ## Development -Run **`make`** from **`sumeru/`** (or workspace Makefile in **`sumeru_custom_addons/`**) before opening a PR. - -| Command | Purpose | -| ----------------------- | ----------------------------------------------- | -| `make setup` | `sumeru.conf` scaffold; `generate` + SWC assets | -| `make run` / `make dev` | `go run ./cmd/sumeru -c sumeru.conf` | -| `make swc` | Rebuild workspace + login JS bundles | -| `make` / `make check` | Lint, tests, `go build ./...` (CI parity) | -| `make build` | Production binary `./sumeru` | -| `make help` | Modules, integration tests, i18n, shell REPL | - -Extra CLI flags: **`EXTRA_RUN_FLAGS`** (e.g. `make run EXTRA_RUN_FLAGS='-p 9090'`). See [tooling docs](https://projectmeru.github.io/sumeru/docs/guides/build/tooling.html). - -SWC sources live in `core/swc/src/`; bundles land in `core/engine/assets/` when you run `make setup` or `make run`. - -## Documentation +From `sumeru/` (or `make` targets in `sumeru_custom_addons/`): **`make`** before PRs; **`make run`** for the server; **`make help`** for modules, tests, and REPL. -| Resource | Link | -| ------------- | ------------------------------------------------------------------------------------------------------- | -| Site | [projectmeru.github.io/sumeru/docs/](https://projectmeru.github.io/sumeru/docs/) | -| Architecture | [docs/architecture-layers.md](docs/architecture-layers.md) | -| Configuration | [guides/start/configuration](https://projectmeru.github.io/sumeru/docs/guides/start/configuration.html) | -| Tooling & CLI | [guides/build/tooling](https://projectmeru.github.io/sumeru/docs/guides/build/tooling.html) | +| Doc | Link | +| --- | --- | +| Platform status & capabilities | [docs/platform-status.md](docs/platform-status.md) | +| Architecture | [docs/architecture-layers.md](docs/architecture-layers.md) | +| Auth / SSO (OIDC, TOTP) | [docs/sso.md](docs/sso.md) | +| Ops (single node, HA, DDL) | [docs/ops-runbook.md](docs/ops-runbook.md) · [docs/ha-ops.md](docs/ha-ops.md) · [docs/ddl-policy.md](docs/ddl-policy.md) | +| Configuration | [sumeru.conf.example](sumeru.conf.example) · [site guide](https://projectmeru.github.io/sumeru/docs/guides/start/configuration.html) | +| Tooling | [site guide](https://projectmeru.github.io/sumeru/docs/guides/build/tooling.html) | +| Full docs site | [projectmeru.github.io/sumeru/docs/](https://projectmeru.github.io/sumeru/docs/) | ## Community -| | | -| ---------------- | --------------------------------------------------------------------------- | -| **Contributing** | [CONTRIBUTING.md](CONTRIBUTING.md) — layout, generate loop, PR expectations | -| **Security** | [SECURITY.md](SECURITY.md) — responsible disclosure | -| **License** | [Apache 2.0](LICENSE) | +[CONTRIBUTING.md](CONTRIBUTING.md) · [SECURITY.md](SECURITY.md) · [Apache 2.0](LICENSE) diff --git a/docs/architecture-layers.md b/docs/architecture-layers.md index 44c56694..cf4041fd 100644 --- a/docs/architecture-layers.md +++ b/docs/architecture-layers.md @@ -1,48 +1,43 @@ -# Sumeru layered architecture +# Layered architecture -Sumeru is a modular ERP built as a **Go monolith** with **PostgreSQL**, **XML-defined** UI and metadata, and a **hybrid web client** (SWC SPA inside a server-rendered shell). This document maps the six runtime layers, how requests flow through them, and how modules extend each other without forking core code. +Sumeru is a **Go monolith**: PostgreSQL, XML views/metadata, and a **hybrid client** (SWC SPA inside a server-rendered shell). Addons register models and data without forking core. -## Six layers +## Layers ```mermaid flowchart TB - subgraph ui [User interface] - SWC["core/swc — FormView, ListView, widgets"] - Web["core/server/web — /web, /web/swc/workspace"] + subgraph ui [UI] + SWC["core/swc — views, widgets"] + Web["core/server/web — /web, workspace JSON"] Render["core/engine/render — HTML shell"] end - subgraph logic [Business logic] + subgraph logic [Logic] RPC["core/server/api — POST /api/rpc"] - ORM["core/orm — CRUD, domain, compute, onchange"] - SDK["core/sdk — addon-facing API"] - Actions["orm.RegisterObjectAction — object buttons"] + ORM["core/orm — CRUD, domain, compute"] + SDK["core/sdk — addon API"] end subgraph modules [Modules] - Manifest["manifest.json — depends, data"] - Install["core/module/install.go — deps, schema, XML sync"] - Discovery["core/module/discovery.go — addons_path"] + Manifest["manifest.json"] + Install["core/module — install, data sync"] end subgraph security [Security] - ACL["sys.access CSV/XML"] - Rules["sys.rule record rules"] - Groups["core.group + implied_ids"] + ACL["sys.access"] + Rules["sys.rule"] FieldACL["sys.field.access"] end subgraph integrations [Integrations] - Mail["addons/mail — chatter, PostMessage"] - Export["/web/export, bulk import"] - Bus["/web/swc/bus WebSocket"] - I18n["i18n export/import CLI"] + Platform["addons/platform — import, export, reports"] + Mail["addons/mail — messages, activities"] + Bus["sys.bus.event + NOTIFY → SWC WebSocket"] end subgraph db [Database] - PG["PostgreSQL"] - Schema["core/orm/schema_sync.go — additive DDL"] - Registry["orm.Registry + modelreg"] + PG[(PostgreSQL)] + Schema["core/orm/schema_sync.go"] end SWC --> RPC @@ -52,86 +47,53 @@ flowchart TB Install --> Schema ORM --> PG Schema --> PG - SDK --> ORM Manifest --> Install + Bus --> PG ``` -| Layer | Primary paths | Request flow | -| ----- | ------------- | ------------ | -| **UI** | [`core/swc/src/views/`](../core/swc/src/views/), [`core/server/web/workspace.go`](../core/server/web/workspace.go), [`core/engine/parser/view_xml.go`](../core/engine/parser/view_xml.go) | Browser → `GET /web/swc/workspace` (arch + records JSON) → SWC renders; mutations → `POST /api/rpc` | -| **Business logic** | [`core/orm/`](../core/orm/), [`core/server/api/dispatch.go`](../core/server/api/dispatch.go), [`core/sdk/`](../core/sdk/) | RPC → `dispatchRPC` → model methods → ORM with ACL/rules applied | -| **Modules** | [`core/module/`](../core/module/), [`addons/*/manifest.json`](../addons/base/manifest.json) | `-i module` → resolve `depends` → `syncModuleSchema` → load `data` XML (two-pass for view inherits) | -| **Security** | [`core/orm/model_acl.go`](../core/orm/model_acl.go), [`core/orm/record_rules.go`](../core/orm/record_rules.go), addon `security/` | Checked on every CRUD/search; rules compiled into SQL WHERE | -| **Integrations** | [`addons/mail/`](../addons/mail/), [`core/server/web/export_handlers.go`](../core/server/web/export_handlers.go), [`core/event/`](../core/event/) | Chatter, exports, event bus, cron — invoked from Go hooks, not XML alone | -| **Database** | [`core/orm/schema_sync.go`](../core/orm/schema_sync.go), [`core/orm/registry.go`](../core/orm/registry.go) | `SyncModels` / `SyncRegistrySchemaForModule` on startup and install | - -## End-to-end traces - -### Open partner form - -1. User opens Contacts → partner list → clicks a row. -2. **`core/server/web`** serves the workspace shell; **`core/swc`** loads via `/static/swc/swc.js`. -3. Client requests workspace JSON (`GET /web/swc/workspace`) with model `core.partner`, view type `form`, and record id. -4. Server loads **`sys.view.arch`** (merged if view inherits were applied), fetches the row from **`core_partner`** via **`core/orm`**, applies field ACL and record rules. -5. SWC **`FormView`** renders fields from arch + record values. - -### Save via RPC - -1. Client posts to **`POST /api/rpc`** (`write` or `create` on `core.partner`). -2. **`core/server/api/dispatch.go`** validates session/API key, resolves the model from **`orm.Registry`**, runs ACL and record rules. -3. **`core/orm`** builds SQL UPDATE/INSERT; **`schema_sync`** has already ensured columns exist from field definitions. -4. Optional hooks: mail chatter, **`event.Subscribe`** listeners in addon `init.go`. - -### Install contacts module - -1. CLI: `go run ./cmd/sumeru -- -c sumeru.conf -i contacts --stop-after-init` -2. **`core/module/install.go`** resolves `depends: ["base"]`, installs base first if needed. -3. **`SyncRegistrySchemaForModule("contacts")`** runs additive DDL for models **owned** by contacts and models **extended** by contacts (see model inherit below). -4. **`core/module/data_sync.go`** loads manifest `data` XML: security, actions, inline views, then **second pass** for `inherit_id` view records. -5. View inherit merges xpath into the parent **`sys.view.arch`** row ([`core/engine/viewinherit/xpath.go`](../core/engine/viewinherit/xpath.go)). - -## Inheritance catalog - -| Mechanism | Status | Where | -| --------- | ------ | ----- | -| **View inherit** (`inherit_id` + xpath) | Implemented | [`core/engine/viewinherit/`](../core/engine/viewinherit/), [`core/module/data_sync_views.go`](../core/module/data_sync_views.go). Example: [`addons/contacts/views/core_partner_form_inherit_views.xml`](../addons/contacts/views/core_partner_form_inherit_views.xml) | -| **Model inherit** (`inherit=` struct tag) | Implemented | [`core/modelmeta/model_spec.go`](../core/modelmeta/model_spec.go), [`core/modelreg/register.go`](../core/modelreg/register.go). Example: [`addons/contacts/models/partner_extend.go`](../addons/contacts/models/partner_extend.go) | -| **Module depends** | Implemented | `manifest.depends` + topological install | -| **Field extension without inherit** | Implemented | `related=`, `compute=` tags in [`core/orm/related.go`](../core/orm/related.go) | -| **Bridge modules** | Pattern | Small addon with `depends` on two apps — see docs on cross-module flows | -| **Events** | Pattern | `event.Subscribe` in addon `init.go` instead of copying Go code | - -### View inherit (example) - -The contacts addon adds **`customer_rank`** to the partner form by inheriting its own base form view: - -```xml - - - - - - - - -``` +| Layer | Paths | Flow | +| ----- | ----- | ---- | +| **UI** | `core/swc/src/views/`, `core/server/web/workspace.go`, `core/engine/swcmeta/` | `GET /web/swc/workspace` → arch + records JSON → SWC; writes → `POST /api/rpc` | +| **Logic** | `core/orm/`, `core/server/api/dispatch.go`, `core/sdk/` | RPC → ACL/rules → SQL | +| **Modules** | `core/module/`, `addons/*/manifest.json` | `-i` / `-u` → depends order → schema sync → XML data (two-pass for view inherits) | +| **Security** | `core/orm/model_acl.go`, `core/orm/record_rules.go`, addon `security/` | Every search/CRUD | +| **Integrations** | `addons/platform/`, `addons/mail/`, `core/server/web/export_handlers.go` | Go services + RPC; not XML-only | +| **Database** | `schema_sync.go`, `orm.Registry` | Additive DDL on install and startup | -### Model inherit (example) +## Traces -Extend **`core.partner`** with a new stored field from the contacts module: +### Open a record form -```go -type PartnerContacts struct { - sdk.Model `sumeru:"inherit=core.partner"` - CustomerRank sdk.Integer `sumeru:"string=Customer Rank,default=0"` -} -``` +1. User opens a menu action → workspace loads `/static/swc/swc.js`. +2. Client requests `GET /web/swc/workspace` with model, view type, optional record id. +3. Server resolves merged `sys.view.arch`, reads row through ORM with field ACL and record rules. +4. SWC `FormView` renders arch + values. + +### Save via JSON-RPC + +1. `POST /api/rpc` — `create` / `write` on the model. +2. `dispatch.go` validates session or API key, applies ACL and record rules. +3. ORM executes SQL; hooks may publish bus events or mail side effects. + +### Install an addon + +1. `go run ./cmd/sumeru -- -c sumeru.conf -i contacts --stop-after-init` +2. Topological `depends`; `SyncRegistrySchemaForModule` for owned/extended models. +3. `data` XML: security, views, actions; **second pass** for `inherit_id` views (`core/engine/viewinherit/`). + +## Extension mechanisms -Run **`make generate`** so **`models/zmodels.go`** registers the struct. On `-u contacts`, schema sync adds the **`customer_rank`** column to **`core_partner`**. +| Mechanism | Where | +| --------- | ----- | +| View inherit (`inherit_id`, xpath) | `core/engine/viewinherit/`, e.g. `addons/contacts/views/core_partner_form_inherit_views.xml` | +| Model inherit (`inherit=` tag) | `core/modelreg/`, e.g. `addons/contacts/models/partner_extend.go` | +| Module `depends` | `core/module/install.go` | +| Related / computed fields | ORM field tags | +| Cross-module Go types | Generated `models/zrefs.go` in addon workspaces | ## See also -- [Architecture overview](https://projectmeru.github.io/sumeru/docs/core/architecture/overview.html) (published docs mirror) +- [platform-status.md](platform-status.md) — maturity and kernel addons +- [sso.md](sso.md) — OIDC, TOTP +- [Published docs](https://projectmeru.github.io/sumeru/docs/core/architecture/overview.html) - [Creating an addon](https://projectmeru.github.io/sumeru/docs/guides/build/creating-an-addon.html) -- [View inherit xpath how-to](https://projectmeru.github.io/sumeru/docs/core/howtos/view-inherit-xpath.html) -- [Model inherit how-to](https://projectmeru.github.io/sumeru/docs/core/howtos/model-inherit.html) diff --git a/docs/ddl-policy.md b/docs/ddl-policy.md index 39ea33bc..0323524c 100644 --- a/docs/ddl-policy.md +++ b/docs/ddl-policy.md @@ -1,30 +1,28 @@ # Schema sync and DDL policy -Sumeru materializes the ORM registry into PostgreSQL with **additive** schema sync (`core/orm/schema_sync.go`): +The ORM materializes registered models into PostgreSQL with **additive** sync in `core/orm/schema_sync.go`: - Creates missing tables and columns - Ensures indexes, unique indexes, and foreign keys (best-effort) - Does **not** drop or rename columns/tables automatically +Module install/update runs scoped sync via `SyncRegistrySchemaForModule` for models owned or extended by that module. + ## Environments | Environment | Policy | |-------------|--------| -| Fresh setup / CI | `SyncRegistrySchema` / module install sync is the source of truth | -| Shared staging / production | Treat sync as **forward-only**. Destructive changes require a reviewed SQL migration run book and backup | +| Fresh DB / CI | Install (`-i`) and startup sync are source of truth | +| Shared staging / production | **Forward-only** additive changes; destructive DDL is a manual, reviewed migration | ## Production rules -1. **Backup** before any manual DDL or module upgrade that alters schema. -2. Prefer **additive** model changes (new columns nullable or with Go-side defaults). -3. For renames/drops: ship a documented SQL script, apply in a maintenance window, then update Go models to match. Do not rely on sync to reverse changes. -4. Module install/update (`-i` / `-u`) still runs scoped sync; review module diffs before production update. -5. Keep `db_sslmode` and pool settings production-appropriate (`sumeru.conf.example`). +1. **Backup** before module `-u` or manual DDL. +2. Prefer **additive** model changes (new nullable columns or defaults applied in Go). +3. **Renames/drops:** ship explicit SQL, apply in a maintenance window, then align Go models. Do not expect sync to remove old columns. +4. Review manifest and model diffs before `-u` on production. +5. Use production `db_sslmode`, pool limits, and secrets from `sumeru.conf.example`. ## Rollback -Schema sync has no automatic rollback. Rollback = restore from backup (or reverse SQL you authored). Application binary rollback alone may fail if the DB already has newer columns (usually safe) or if you manually dropped required columns (unsafe). - -## Future - -A recorded migration ledger (versioned SQL + apply tracking) may replace ad-hoc scripts; until then this document is the operational contract. +There is no automatic schema rollback. Restore from backup or run reverse SQL you authored. Rolling back the binary alone is usually safe if only new columns were added; it is unsafe if required columns were dropped manually. diff --git a/docs/ha-ops.md b/docs/ha-ops.md index 30d60400..356c2601 100644 --- a/docs/ha-ops.md +++ b/docs/ha-ops.md @@ -1,21 +1,22 @@ -# High availability operations (Phase 6) +# High availability operations -Sumeru sessions are **DB-backed** (`sys.session`), so sticky sessions are not required for auth. Session cookies are browser-scoped (not multi-day persistent); idle timeout ~8h with a 24h DB ceiling. +Sumeru sessions are **DB-backed** (`sys.session`), so HTTP load balancers do **not** need sticky sessions for cookie auth. Session cookies are browser-scoped; idle timeout ~8h with a 24h DB `expires_at` ceiling. -## Requirements before multi-instance +## Before running multiple app instances -1. **`csrf_secret` / `SUMERU_CSRF_SECRET`** — shared across all app processes (see `sumeru.conf.example`). -2. **Shared PostgreSQL** — one primary; optional `db_read_replica_dsn` for read RPCs. -3. **`metrics_scrape_token`** — scrape `/metrics` without an admin browser session. -4. **Probes** — liveness `GET /api/health`; readiness `GET /api/ready` (DB ping). -5. **Queue** — in-process pub/sub does not cross instances. Use `queue.SetPublishMirrorHook` (or an external broker) so outbox/bus events fan out; WebSocket bus remains per-instance unless a shared pub/sub is wired. +1. **`csrf_secret` / `SUMERU_CSRF_SECRET`** — identical on every process (`sumeru.conf.example`). +2. **One PostgreSQL primary** — all instances share the same database; optional `db_read_replica_dsn` for read-heavy RPC paths. +3. **`metrics_scrape_token` / `SUMERU_METRICS_SCRAPE_TOKEN`** — scrape `GET /metrics` without an admin browser session. +4. **Health probes** — liveness `GET /api/health`; readiness `GET /api/ready` (DB ping). +5. **SWC bus** — events persist to `sys.bus.event` and fan out with **PostgreSQL NOTIFY** (`StartBusListener` on each process). WebSocket clients attach to one instance; NOTIFY delivers cross-instance fan-out when all nodes share the same DB. +6. **Optional queue mirror** — in-process `core/queue` topics can use `queue.SetPublishMirrorHook` (e.g. Redis) if you add workers outside the monolith; not required for standard SWC bus. ## Rolling deploy -1. Backup DB. -2. Apply additive schema / module updates (`docs/ddl-policy.md`). -3. Roll instances behind the load balancer; drain with SIGTERM (20s shutdown). +1. Backup the database ([ops-runbook.md](ops-runbook.md)). +2. Apply additive schema / module updates per [ddl-policy.md](ddl-policy.md). +3. Roll instances behind the load balancer; allow SIGTERM drain (~20s shutdown). -## SSO / IdP +## Identity -Native SAML/OIDC is not shipped yet. See [sso.md](sso.md). Until then use strong passwords, system-admin gated password changes (`orm.SetUserPassword`), and the login-link notify action (not a tokenized reset). +OIDC/OAuth and TOTP are built in — see [sso.md](sso.md). SAML is not shipped. diff --git a/docs/ops-runbook.md b/docs/ops-runbook.md index 08133a59..b93d52a4 100644 --- a/docs/ops-runbook.md +++ b/docs/ops-runbook.md @@ -1,25 +1,41 @@ # Operations runbook (single-node pilot) +Alpha kernel — use for pilots and staging only. See [platform-status.md](platform-status.md). + ## Deploy -1. Set secrets via env: `SUMERU_DB_PASSWORD`, `SUMERU_CSRF_SECRET`, optional `SUMERU_METRICS_SCRAPE_TOKEN`. -2. `dev_mode=false`, `rate_limit_rpm` ≥ 120 (auto-defaulted when not in dev). +1. Secrets via env: `SUMERU_DB_PASSWORD`, `SUMERU_CSRF_SECRET`, optional `SUMERU_METRICS_SCRAPE_TOKEN`, SMTP vars for mail notify. +2. Production-ish flags: `dev_mode=false`; set `rate_limit_rpm` (defaults to 120 when unset and not in dev). 3. Start: `./sumeru -c sumeru.conf` or `docker compose -f docker-compose.prod.yml up --build`. -4. Probes: `/api/health` (live), `/api/ready` (DB). +4. Probes: `GET /api/health` (live), `GET /api/ready` (database). + +Optional shell presence (off by default): + +- `close_session_on_last_tab = true` — SWC tab lease + `POST /web/session/touch` heartbeat; when all tabs stop, session ends after `session_browser_grace_seconds`. +- When **false** (default), closing tabs does not revoke the session until idle/DB expiry. ## Backup / restore -- Use `pg_dump` / `pg_restore` (or your managed Postgres backup). -- Restore DB before rolling back application binaries if schema advanced (see `ddl-policy.md`). +- `pg_dump` / managed Postgres backups. +- Restore DB before rolling back binaries if schema moved forward ([ddl-policy.md](ddl-policy.md)). -## Incident +## Incident response -- Revoke sessions: delete rows from `sys.session` or destroy cookie via logout. -- Browser sessions are non-persistent (session cookie) with ~8h idle / 24h DB ceiling; closing the last Sumeru tab triggers logout via beacon. -- Rotate `csrf_secret` only with a full restart of all instances (invalidates CSRF tokens). -- Check `/metrics` (Bearer scrape token) and JSON logs (`request_id`). +| Action | How | +| ------ | --- | +| Revoke all sessions for a user | Delete `sys.session` rows for `user_id` or use admin logout flows | +| Force re-login everywhere | Rotate sessions table or invalidate cookies via logout | +| CSRF invalidation | Changing `csrf_secret` requires restart of **all** instances | +| Observability | JSON logs (`request_id`); `GET /metrics` with scrape token | + +Session timing: ~8h idle behavior with 24h DB ceiling; see `core/server/web` session resolution. ## Rollback -1. Point LB to previous image/binary. -2. If DDL was applied, restore DB or run reverse SQL from the change ticket. +1. Point traffic to the previous binary/image. +2. If DDL or `-u` module sync advanced schema, restore DB or run authored reverse SQL — sync does not drop columns automatically. + +## Related + +- Multi-instance: [ha-ops.md](ha-ops.md) +- Auth / IdP: [sso.md](sso.md) diff --git a/docs/platform-status.md b/docs/platform-status.md new file mode 100644 index 00000000..d6bd3214 --- /dev/null +++ b/docs/platform-status.md @@ -0,0 +1,48 @@ +# Platform status (kernel) + +Maturity of the **`sumeru` repository** (Go engine + `addons/`). Business apps in [sumeru_addons](https://github.com/ProjectMeru/sumeru_addons) are tracked separately. + +**Stage:** **Alpha (platform kernel)** — development, demos, and custom modules. Not for production or regulated workloads. JSON-RPC payloads and UX may change between releases. + +## Capability matrix + +| Area | Status | Notes | +| ---- | ------ | ----- | +| Modules & ORM | **Ready** | Manifests, install/update, compute, domains, multi-company, elevated context | +| Security | **Ready** | Groups, record rules, model ACL, field ACL UI | +| Views & SWC | **Ready** | List, form, kanban, graph, pivot, calendar, gantt, map, cohort, hierarchy, activity; view inherit | +| JSON-RPC | **Ready** | `POST /api/rpc` (session or API key) — primary integration API | +| Reports, import/export | **Ready** | Document reports; import wizard; async export / bulk jobs (`platform`) | +| Mail & activities | **Partial** | `mail` addon: messages, followers, notifications, outbound queue, activity board; no inbound IMAP | +| Realtime | **Ready** | `sys.bus.event`, PG NOTIFY, SWC WebSocket reconnect | +| Portal | **Partial** | `/portal` shell and share links | +| Auth | **Ready** | Password, OIDC/OAuth providers, TOTP, trusted device — [sso.md](sso.md) | +| Automation | **Ready** | Cron, server actions (`automation` addon) | +| Currency, UoM, properties | **Ready** | `currency`, `uom` addons; monetary fields; JSONB properties + `sys.property.definition` | +| IM | **Ready** | Internal chat (`im` addon), separate from record mail | +| Studio, website CMS, offline PWA | **Roadmap** | Not in kernel today | +| Inbound mail gateway | **Not planned** | Outbound + in-app messaging only | +| Public REST API | **Not planned** | Use JSON-RPC and HTTP helpers (export, content, health) | + +## Kernel addons (shipped in this repo) + +| Module | Role | +| ------ | ---- | +| `base` | Users, companies, partners, security, auth providers | +| `platform` | Attachments, sequences, parameters, reports, import/export (auto_install) | +| `currency`, `uom` | Currency catalog, rates, units of measure | +| `geo`, `i18n` | Geography, translations | +| `im` | Internal messaging | +| `mail` | Record messages and activities | +| `contacts`, `calendar` | Reference apps | +| `automation`, `audit`, `digest` | Technical automation and audit | +| `sumeru_ai` | Optional AI hooks (`auto_import: false`) | + +Manifest `depends` and `auto_install` flags are authoritative; run `make generate` after dependency changes in downstream workspaces. + +## Integrations + +- **JSON-RPC:** `POST /api/rpc` with browser session or API key. +- **HTTP:** Content download, export endpoints, health/readiness — see `core/server/web` routes and [architecture-layers.md](architecture-layers.md). + +Extend via addons and RPC, not a separate REST surface. diff --git a/docs/sso.md b/docs/sso.md index 99683bda..d7fb86cc 100644 --- a/docs/sso.md +++ b/docs/sso.md @@ -1,16 +1,41 @@ -# SSO / identity providers +# Authentication and SSO -Sumeru does **not** yet include built-in SAML or OIDC login. +Sumeru ships **OIDC/OAuth2 login** (authorization code + PKCE), **TOTP** second factor, and **trusted devices**. **SAML is not implemented** — use IdPs that speak OIDC. -## Current options +## OIDC / OAuth providers -- Local `core.user` passwords (bcrypt) via UI `password_plain` / `orm.SetUserPassword` -- API keys (`sk_…`) for automation -- Admin **login-link notify** email (`ActionResetPassword`) — sends a login URL only; it does **not** issue a password-reset token +Configure under **Settings → Security → Authentication providers** (`sys.auth.provider`). -## Recommended enterprise path +| Field / behavior | Notes | +| ---------------- | ----- | +| Routes | `GET /web/auth/oauth/start?provider=`, `GET /web/auth/oauth/callback` | +| PKCE | S256 challenge on start; verifier in HttpOnly state cookie | +| Token exchange | Uses provider `token_url` or `issuer_url` + `/token` | +| `id_token` | When `jwks_url` is set, signature verified (RS256/ES256) before account link | +| JIT / link | Policies on provider control link-by-email vs deny; identities stored on `core.user.identity` | +| Login UI | Enabled providers appear as SSO buttons on `/web/login` | -1. Terminate SSO at a reverse proxy or identity-aware proxy (e.g. OAuth2 proxy) and map the authenticated identity into Sumeru in a future bridge module, **or** -2. Implement OIDC authorization-code login as a `base` extension when product prioritizes it. +Local password login remains available unless system parameter `auth.local_enabled` is `false` **and** at least one provider is enabled. -Track status against the enterprise readiness DoD before removing the pre-alpha banner. +Secrets (`client_secret`, etc.) are sensitive — see `core/security/fields.go` registry. + +## TOTP + +- Users enroll under **Settings → Account security** (`totp_enabled`, `totp_secret` on `core.user`). +- After password or OAuth, login may redirect to **`/web/login/totp`** until a valid code is entered (pending-MFA cookie, HMAC-bound). +- **Trusted device** cookie (`sumeru_trusted_device`) skips TOTP for that browser when valid. + +## Other auth surfaces + +| Mechanism | Purpose | +| --------- | ------- | +| Session cookie | DB-backed `sys.session`; see [ops-runbook.md](ops-runbook.md) | +| API keys | `sk_…` for JSON-RPC automation | +| Login-link notify | Admin action sends login URL email — **not** a password-reset token | +| Portal | Separate portal session routes under `/portal/*` | + +## Operations + +- Rotate provider secrets in UI; disable provider before decommissioning IdP clients. +- Shared **`csrf_secret`** required when running multiple app instances ([ha-ops.md](ha-ops.md)). +- For air-gapped or proxy-only IdPs, terminate trust at the reverse proxy only if you accept that Sumeru will not see OIDC tokens (custom bridge addon).