monie-backend/AGENTS.md

Monie Backend Agent Guide

Scope

This file applies only to monie-backend.

monie-backend is the source of truth for business logic across Monie apps:

• monie-web
• monie-mobile
• monie-widget
• monie-landing (limited, mostly public marketing integrations)

Do not move backend rules to frontend projects "for convenience".

---

Current Architecture

NestJS monorepo with multiple apps in apps/:

• gateway (apps/gateway) — public API entrypoint / aggregation layer
• auth (apps/auth) — authentication and authorization
• bookings (apps/bookings) — booking-related APIs
• tasks (apps/tasks) — tasks domain APIs
• notifications (apps/notifications) — notification domain APIs

Default ports:

• AUTH_PORT=3000
• GATEWAY_PORT=3001
• TASKS_PORT=3002
• NOTIFICATIONS_PORT=3003
• BOOKING_PORT=3004

---

Runtime Commands

Use npm scripts from package.json:

• npm run start:dev — run all apps in watch mode
• npm run start:gateway
• npm run start:auth
• npm run start:bookings
• npm run start:tasks
• npm run start:notifications
• npm run build
• npm run test
• npm run test:e2e
• npm run check (Biome check)
• npm run lint (Biome lint with write)
• npm run format (Biome format with write)

---

Engineering Rules

1) Business Logic Ownership

• Keep domain rules in domain apps/services (auth, bookings, tasks, notifications).
• Keep gateway thin unless aggregation/proxy behavior is explicitly needed.
• Do not keep critical decisions only in controllers.

2) API Design

• Use clear route naming by domain.
• Keep DTOs explicit; avoid loosely typed payloads.
• Validate input on server side for all external entrypoints.
• Return consistent response shapes for similar endpoints.

3) Security

• Never hardcode secrets/tokens in source code.
• Read secrets from environment variables.
• Do not store plain passwords (use hashing once persistence is added).
• Treat auth/session flows as high-risk changes: require tests.

4) Data and Contracts

• Backend is canonical for entity rules and invariants.
• Public/widget-safe endpoints must not expose internal-only fields.
• Prefer stable identifiers for public integrations (widgetKey, slug, etc.), not internal DB IDs where avoidable.

5) Error Handling

• Use HTTP exceptions intentionally with clear status codes.
• Avoid swallowing upstream errors.
• Keep error messages useful but do not leak secrets/internal stack details to clients.

6) Code Quality

• Language: TypeScript.
• Keep modules focused by domain.
• Prefer readable code over clever abstractions.
• Use Biome as the only formatter/linter in this project.

---

Migration Notes (Old Backend)

Legacy code exists in ../old/monie-backend.

When migrating:

• migrate by domain, not by mass copy;
• remove deprecated scaffolding and sample-only code;
• do not copy insecure placeholders (e.g., hardcoded JWT secrets);
• adapt old code to current monorepo structure and Biome formatting.

Suggested migration order:

1. auth baseline (login/logout/profile + guards/roles)
2. bookings public read endpoints needed by widget/web
3. tasks and notifications
4. gateway aggregation behavior (if still needed)

---

Testing Expectations

For any non-trivial change:

• add or update unit tests for changed services/controllers;
• run npm run test;
• run npm run test:e2e when routes/bootstrapping are touched.

For auth, booking rules, and access-control changes, tests are mandatory.

---

Done Criteria

A backend task is considered done when:

1. scope is limited to required app/module(s);
2. API behavior is validated (tests and/or manual endpoint check);
3. npm run check passes;
4. npm run build passes;
5. no secrets or temporary hardcoded sensitive values are introduced.

---

Commit Convention

Use Conventional Commits with backend scope when useful:

• feat(backend): ...
• fix(backend): ...
• refactor(backend): ...
• test(backend): ...
• chore(backend): ...

If change is isolated to a backend app, scope can be more specific:

• feat(auth): ...
• feat(bookings): ...
• fix(gateway): ...