chore: migrate backend to monorepo apps and biome

AGENTS.md

@@ -0,0 +1,142 @@
+# 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): ...`