Corely — AI-native modular ERP kernel

A modular ERP kernel that starts with freelancer workflows (expenses, invoices, assistant) and scales into restaurant, hotel, and factory packs without forking code.

Table of Contents

• Corely — AI-native modular ERP kernel
  • Table of Contents
  • What is Corely?
  • Key features
    • Kernel & modularity
    • Reliability primitives
    • Security primitives
    • Developer experience
  • Open-source kernel, commercial packs
  • Architecture at a glance
    • Dependency direction rules
  • Monorepo layout
  • Getting started
    • Prerequisites
    • Quick start
      • UI-first (web + mock server)
      • Full stack (web + API + Postgres/Redis)
    • Environment files
  • Environment variables
  • Scripts
  • Development modes
  • Built in public
  • How to add a new module
  • Contributing
  • Security
  • Roadmap
  • License
  • Acknowledgements

What is Corely?

• A modular kernel built for freelancer workflows (expenses, invoices, assistant) that can layer in full ERP packs (restaurant, hotel, factory) without duplicating the core.
• AI-native by design: contracts define tool schemas, assistant endpoints run through the API with auditable tool executions, retries are idempotent, and every action is logged for traceability.
• Bounded contexts keep each module’s domain model, use cases, and migrations isolated so teams can own vertical packs safely.
• Hexagonal ports/adapters let use cases stay framework-free while adapters live in NestJS, Prisma, Redis, or UI layers.
• Outbox + API-hosted background jobs power reliable automations, and CQRS-lite read models keep dashboards responsive without polluting the write model.
• Idempotency keys, audit trails, and tenant scoping are defaults so even AI or POS retries stay safe.

Key features

Kernel & modularity

• Modular monolith with shared contracts (packages/contracts), pure domain rules (packages/domain), and a kernel of standard use cases.
• Packs add UI, migrations, and integrations in their own folders so restaurant/hotel/factory features compose the kernel instead of fork it.
• Clear ownership boundaries remove direct cross-module DB writes; modules talk through contracts, events, and the API surface.

Reliability primitives

• Outbox pattern plus API-hosted background execution deliver domain events, retries, and process managers for automations.
• CQRS-lite read services keep dashboards fast while write use cases remain strict and transactional.
• Every write command/tool call carries an idempotency key plus an audit log entry by default.

Security primitives

• Tenant-aware schemata (all tables include tenantId checks) and RBAC/ABAC guards in the API.
• Declarative Tenancy: Use cases are protected by @RequireTenant() decorators that enforce context validation at the orchestration layer.
• Audit log captures critical actions, including AI tool executions and POS commands, with immutable metadata.
• Tool runs surface confidence, provenance, and trace IDs so consumers can safely retry or investigate.

Developer experience

• pnpm workspace orchestrates apps (apps/web, apps/pos, apps/e2e), services (services/api, services/mock-server), and shared packages.
• Contracts package centralizes schemas, enums, and tool cards so frontend and backend speak the same language.
• Mock server simulates latency, pagination, idempotency, and assistant-tool endpoints, enabling a UI-first workflow before the full stack is ready.
• Prompt definitions and versioning live in docs/prompt-management.md.

Open-source kernel, commercial packs

• Core OSS kernel: everything in this repository is AGPL-3.0-only unless a file or folder states otherwise.
• Enterprise Packs / EE: distributed separately under a commercial license; they integrate via ports/interfaces and runtime registration (no direct OSS imports).
• Trademarks: “Corely” name and logos are protected by trademark and brand usage rules.
• Details: see docs/licensing.md, ee/README.md, and TRADEMARKS.md.

Architecture at a glance

DDD bounded contexts → Hexagonal ports/adapters → Outbox + Background Jobs → CQRS-lite reads + idempotent commands + audit by default.

flowchart LR
  subgraph Clients
    Web["apps/web (Vite)"]
    POS["apps/pos (POS shell)"]
  end
  subgraph Shared
    Contracts["packages/contracts"]
    Domain["packages/domain"]
    Data["packages/data"]
  end
  subgraph Backend
    API["services/api"]
    Mock["services/mock-server"]
  end
  Web --> Contracts
  Web --> Domain
  POS --> Contracts
  POS --> Domain
  API --> Contracts
  API --> Domain
  API --> Data
  Mock --> Contracts

Loading

Dependency direction rules

• apps/web & apps/pos → packages/contracts, packages/domain
• services/api → packages/contracts, packages/domain, packages/data
• packages/domain → packages/contracts
• Forbidden: packages/contracts importing other workspace code, frontend importing backend internals, backend importing UI assets, or any module writing another module’s tables directly.
• Architecture patterns: DDD bounded contexts, Hexagonal ports/adapters, Outbox + background jobs for automation, CQRS-lite reads for dashboards, idempotent commands and audit trails as defaults.

Modules

The system is composed of vertical slice modules, each owning its domain logic, data, and API surface:

• Foundation: identity, workspaces, platform (apps/packs), customization (fields), documents (storage).
• Commerce: crm (deals/pipelines), sales (quotes/orders), invoices, payment-methods, products, tax.
• Operations: inventory, purchasing, expenses, projects (coming soon).
• Automation: automation (triggers/actions), workflow (process engine), approvals, ai-copilot.
• Verticals: pos (point of sale), booking (coming soon), production (coming soon).

Monorepo layout

apps/
  e2e/                        # End-to-end suites
  pos/                        # Offline-first POS shell
  public-web/                 # Next.js public site (portfolios, rentals, CMS)
  web/                        # Vite-based admin UI

services/
  api/                        # NestJS API (RBAC, tools, workflows, background jobs)
  mock-server/                # Dedicated mock server for UI-first work

packages/
  api-client/
  auth-client/
  config/
  contracts/
  core/
  data/
  domain/
  email-templates/
  kernel/
  offline-core/
  offline-rn/
  offline-web/
  pos-core/
  testkit/
  tooling/

docs/
assets/
docker/
scripts/

Getting started

Prerequisites

• Node.js 22.19+ (LTS recommended)
• pnpm 10+
• Docker (optional: Postgres/Redis via docker-compose.dev.yml, docker-compose.local.yml, or Alpine scripts)

Quick start

1. Install dependencies and copy env scaffolding:

   pnpm install
   cp .env.example .env

2. Set VITE_API_BASE_URL to http://localhost:4000 for the mock profile or http://localhost:3000 for the full stack.
3. Start the stack you need:

UI-first (web + mock server)

pnpm dev:mock
pnpm dev:web
pnpm dev:public

Mock server routes live under services/mock-server/src/routes; latency, pagination, and idempotency middleware keep the experience close to the real API.

Full stack (web + API + Postgres/Redis)

pnpm dev:api
pnpm dev:web
pnpm dev:public

Ensure Postgres/Redis are reachable (use docker compose -f docker-compose.dev.yml up if needed). When you want everything wired together, pnpm dev builds packages then starts all services.

Environment files

• Global defaults: .env.example, .env.dev.example, .env.e2e.example; copy the one that matches your workflow into a .env file at the repo root.
• Services and apps pick values from that .env (web uses VITE_ prefixed keys, API references connection strings directly).

Environment variables

Name	Used by	Example	Notes
DATABASE_URL	@corely/api, @corely/data	postgresql://corely:corely@postgres:5432/corely?schema=public	Prisma connection for commands, outbox, and read models.
REDIS_URL	@corely/api	redis://redis:6379	Queues, locks, rate limits, idempotency caches.
VITE_API_BASE_URL	apps/web, apps/pos	http://localhost:4000	Switch between mock (4000) and real API (3000).
LOG_LEVEL	All services	debug	Controls structured logging verbosity.
AI_MODEL_PROVIDER	@corely/api	openai	Selects openai or anthropic for Copilot tool runs.
OPENAI_API_KEY / ANTHROPIC_API_KEY	@corely/api	(redacted)	Provider credentials for assistant/tool calls; keep secret.
EMAIL_PROVIDER	@corely/api	resend	Controls transactional email adapter.
WEB_PORT, PORT, MOCK_PORT	Apps/services	8080, 3000, 4000	Override ports when composing services locally.

Scripts

Common scripts include:

• pnpm dev – builds shared packages and runs all services/apps in parallel.
• pnpm dev:web, pnpm dev:mock, pnpm dev:api, pnpm dev:api:debug – start each surface individually.
• pnpm build, pnpm build:web, pnpm build:api – compile packages plus apps/services.
• pnpm typecheck, pnpm lint, pnpm format, pnpm format:check – workspace-wide quality gates.
• pnpm check – lint + typecheck.
• pnpm prisma:migrate – apply committed Prisma migrations for @corely/data.
• pnpm prisma:migrate:dev – create/apply local development migrations; requires PostgreSQL CREATEDB or SHADOW_DATABASE_URL.
• pnpm prisma:generate – regenerate the Prisma client.

Development modes

• Mock-first / UI-first: apps/web (and apps/pos) call services/mock-server. Mock middleware simulates latency/pagination, enforces idempotency, and exposes assistant tool endpoints, so UI work keeps moving before backend features land.
• Full backend stack: services/api uses NestJS guards, Prisma, the outbox table, idempotency ports, workflow queues, and background handlers. packages/data owns the Prisma client and repositories.

Built in public

• Progress lives in docs such as docs/IMPLEMENTATION_SUMMARY.md, CODE_SHARING_ANALYSIS.md, and the per-domain status notes (ACCOUNTING_CORE_STATUS.md, POS_IMPLEMENTATION_STATUS.md). Watch those for what is happening now.
• Contributors can help by picking tasks from the implementation docs, updating the mock server when new contracts arrive, or improving module guides (docs/MODULE_IMPLEMENTATION_GUIDE.md, docs/MODULE-TEMPLATE.md).
• Large changes start with an issue describing the intent; small PRs that include updated tests/docs are most welcome.

How to add a new module

1. Contracts first: add Zod schemas, enums, and tool definitions inside packages/contracts/src/<module> so web, POS, and API share the surface.
2. Backend module: create services/api/src/modules/<module> folders with domains, use cases, DTOs, and Nest controllers that depend only on ports/adapters.
3. Database persistence: For small modules, use ext.kv or ext.entity_attr (no new tables). For larger modules, add models to packages/data/prisma/schema/*.prisma assigned to the correct domain bucket (e.g., @@schema("crm")) and create a repository in packages/data/src.
4. Frontend module: mirror the module in apps/web/src/modules/<module> (screens, hooks, routes) and point to the shared contracts plus the HTTP client.
5. Mock routes: register UI-first routes/seeds in services/mock-server/src/routes so the mock server stays up to date.

Keep the boundaries: API modules use ports/interfaces, background jobs consume the module’s events, and clients never import backend internals.

Contributing

• Open an issue for any larger initiative so maintainers can track scope before code.
• Small, focused PRs that pass pnpm lint, pnpm typecheck, and relevant tests get reviewed faster.
• Update docs or docs/IMPLEMENTATION_SUMMARY.md when you touch workflows, contracts, or module behavior.
• Code style follows the shared configs (eslint.config.js, prettier.config.js). Run pnpm format and pnpm lint:fix when you add or move files.
• See CONTRIBUTING.md for setup, DCO sign-off, and review expectations. Community standards live in CODE_OF_CONDUCT.md.

Security

Please follow SECURITY.md for private reporting and response expectations. Placeholder contact: <SECURITY_EMAIL>.

Roadmap

Subject to change.

• Module registry and pack metadata so teams can enable restaurant/hotel/factory workflows with one settings switch.
• Workflow editor integration that composes use-case graphs for approvals, approvals, and multi-step automations.
• POS offline build-out: queue durability, shift sessions, floor plan workflows, and manager approvals.
• AI Copilot improvements: richer tool cards, assistant run auditing, and more deterministic apply/dismiss flows.
• Vertical pack work: kitchen display flows, room folio billing, manufacturing BOM routing, and pack-specific migrations.
• Observability upgrades: structured logs with trace IDs, read-model telemetry, and outbox monitoring dashboards.
• Marketplace for connectors (webhooks, real-time adapters) that plug into the outbox/background automation surface.

License

Corely Community is licensed under AGPL-3.0-only. Enterprise Packs are commercial and distributed separately. Trademarks are governed by TRADEMARKS.md. See LICENSE and docs/licensing.md for details.

Acknowledgements

Built on Vite, React, NestJS, Prisma, BullMQ, and XState along with the ideas documented in docs/architect.md and docs/overall-structure.md.