Getting started

Prerequisites

• Go — the version in go.mod (1.26)
• Node ≥ 24 and pnpm (the repo pins the version in packageManager)
• Docker running (Postgres 17 and MinIO run in containers)

Run everything

pnpm start

This runs scripts/dev-all.sh: it starts the backend stack (scripts/dev-stack.sh), waits for /v1/health to answer, then starts the Vite dev server. Ctrl-C stops the api and web server; the Docker containers keep running.

Piece	Where
Web app (Vite, proxies /v1)	http://localhost:5173
API (cmd/api)	http://localhost:3000
Postgres 17	container erp-dev-pg, port from ERP_PG_PORT / PG_PORT
MinIO (object storage)	container erp-dev-minio, port 59000

The first run creates a demo organization (Demo Sdn Bhd) with orgadmin create-org and seeds it through the public API. Demo users and their roles are listed in web/e2e/README.md.

scripts/dev-stack.sh down removes the containers and the dev state, data volumes included.

Common commands

Command	What it does
make test	go test ./... -count=1 — needs Docker, tests run against real Postgres
make lint	go vet and a gofmt check
make generate	sqlc, oapi-codegen, vocabulary, public API, web schema
make build	builds api, worker, operator, migrate, telegram-webhook into bin/
make migrate	applies goose migrations
make web	install, typecheck, lint, test and build the frontend

While iterating, test only the packages you touched (go test ./internal/modules/crm/...); run the full suite once before committing.

Repository layout

Path	What lives there
api/openapi.yaml	The contract. Handlers implement interfaces generated from it.
cmd/	Binaries: api, worker, migrate, operator, orgadmin, telegram-webhook, myinvois-fake
internal/kernel, platform, modules	The three tiers — see the architecture overview
db/	goose migrations and sqlc queries
web/	React 19 + Vite frontend
packages/contracts	TypeScript client generated from openapi.yaml
docs/	Everything on this site that is not hand-written under docs-site/pages/

Before you change anything

1. Read the roadmap and tick items as they land. If what you are building is not on it, say so first.
2. Read the project invariants. Most are enforced by a test that fails the build.
3. Change api/openapi.yaml first when an endpoint changes; the build fails if a handler drifts from it.

Working on this documentation

pnpm -C docs-site install
pnpm -C docs-site dev      # syncs docs/ then serves with live reload
pnpm -C docs-site build    # fails on broken internal links

Edit the Markdown under docs/; do not edit anything in docs-site/src/content/, it is regenerated from docs/ and the Go package comments on every run.