Skip to main content

docs/standards/

Short, actionable standards for day-to-day work on Ghasi Melmastoon. These distill the long-form specs in docs/01-… through docs/19-… and the per-service bundles under services/<name>/. When a spec changes, the matching standards doc must be updated in the same commit.

FilePurposeWhen to consult
DEVELOPMENT_WORKFLOW.mdMandatory: every code change is tied to a backlog work item (US-MEL-* / MEL-*); specs are in freeze except via ADR; update ../backlog/IMPLEMENTATION_STATUS.md when story state changes.Before writing code, opening a PR, or when an agent would “add a feature” not on the backlog.
SERVICE_TEMPLATE.mdThe 17 required docs every service must own + the NestJS directory skeleton + the per-service CI gate + the readiness gate.Whenever you start a new service, audit an existing one, or scaffold code in the ghasi-melmastoon monorepo.
NAMING.mdOne-page naming authority: services, files, classes, branded IDs, events, DB tables/columns/indexes, API paths, ID prefixes (tnt_, rsv_, key_, …), env vars, error codes (MELMASTOON.<DOMAIN>.<CODE>).Every PR that introduces a new symbol, file, route, table, event subject, or environment variable.
ERROR_CODES.mdCanonical machine-readable error registry grouped by domain (RESERVATION, INVENTORY, BILLING, LOCK, SYNC, AI, …).Every API or sync error returned to a client. Never invent a new code without adding it here in the same PR.
DEFINITION_OF_DONE.mdPer-PR merge checklist: lint, typecheck, unit + tenant-isolation + outbox + inbox tests, OpenAPI diff gate, event schema registration, observability, security review, i18n + RTL screenshots, accessibility, changelog, ADR.Every PR before requesting review.

Two-repo split​

This standards directory lives in the documentation repo (ghasi-e-documentation/ghasi-melmastoon/). Runnable code will live in a separate application monorepo (the future ghasi-melmastoon repo). The split mirrors Ghasi-edTech so that prompts, commands, audits, and tooling are reusable.

ArtifactLocation
Per-service spec bundles (17 docs each)This repo: services/<name>/
Strategic docs (01..19-*.md, 03-microservices/, architecture/, frontend/, journeys/, observability/, testing/, risks/, roadmap/)This repo: docs/
NestJS service code (src/{domain,application,infrastructure,presentation}, tests, openapi.json, migrations)Future code monorepo: services/<name>/
AGENTS.md, CLAUDE.md, .cursorrules, .cursor/rules/*.mdc, command playbooksFuture code monorepo, repo root

The scaffolding command (forthcoming /scaffold-service in the code monorepo) reads these specs as a preflight gate. It never writes back to them.

Spec set (source of truth — all in this repo)​

  • docs/01-product-overview.md
  • docs/02-enterprise-architecture.md
  • docs/03-microservices/ (one summary file per service; 22 services total)
  • docs/04-event-driven-architecture.md
  • docs/05-api-design.md
  • docs/06-data-models.md
  • docs/07-security-compliance-tenancy.md
  • docs/08-ai-architecture.md
  • docs/09-lock-and-key-integration.md
  • docs/10-payments-architecture.md
  • docs/frontend/01-web-and-mobile-specification.md
  • docs/frontend/02-theming-and-tenant-config.md
  • docs/frontend/desktop/06-desktop-app-specification.md
  • docs/journeys/01-core-user-journeys.md
  • docs/standards/01-engineering-standards.md
  • docs/testing/01-testing-strategy-qa.md
  • docs/observability/01-observability.md
  • docs/risks/01-risks-and-tradeoffs.md
  • docs/roadmap/01-product-roadmap.md
  • docs/architecture/ (ADRs)

Spec vs code conflict: spec wins. Update code, not spec — unless the user explicitly approves the spec change in the same PR (and the change is captured in an ADR under docs/architecture/).

Stack reminder (from README.md)​

  • Desktop backoffice is Electron (Node 20 main + Chromium renderer + Vite + React + better-sqlite3 + ONNX Runtime Node, packaged with electron-builder, signed and auto-updated via electron-updater). Never Tauri.
  • Backend services are NestJS in TypeScript with Clean Architecture + DDD; the domain layer is framework-free.
  • Data: PostgreSQL on Cloud SQL (per-service schema, RLS by tenant_id), GCP Pub/Sub for events, pgvector for embeddings, SQLite on desktop, Firestore for desktop sync state + outbox cursors.

If you are unsure where a rule belongs, default to the closest existing standards doc and update the spec set in the same PR.