# HostelCare backend instructions

## Architecture

The backend is a TypeScript Express API using Prisma and PostgreSQL.

- `src/app.ts` configures the Express application.
- `src/server.ts` starts the process.
- `src/modules/<feature>/` contains feature routes, controllers, services,
  schemas, and related code.
- `src/middleware/` contains cross-cutting request concerns.
- `src/lib/` contains shared infrastructure and security helpers.
- `prisma/schema.prisma` and `prisma/migrations/` define the database contract.

Follow the existing route → controller → service → Prisma pattern. Keep HTTP
translation in controllers/routes and business rules in services. Validate
input at the boundary with Zod. Reuse existing middleware and helpers before
adding new ones.

## Security and tenancy

- This is shared-schema multi-tenancy. Every tenant-scoped query must use the
  scoped Prisma client and preserve the request tenant context.
- Use `prismaUnscoped` only for explicitly permitted pre-authentication or
  SUPER_ADMIN operations already following the existing pattern.
- Treat authentication, authorization, property scoping, and plan limits as
  separate checks. Do not replace permission checks with role-name checks when
  custom roles are supported.
- Never trust tenant, property, user, or role identifiers supplied by a client.
- Do not return passwords, refresh tokens, secrets, internal stack traces, or
  sensitive storage details.
- New endpoints must define authentication, permission, tenant/property scope,
  input validation, error behavior, and isolation tests where relevant.

## Database and API changes

- Inspect existing schema and migrations before changing Prisma models.
- Create a migration for schema changes; never edit an already-applied
  migration to repair history.
- Keep response shapes intentional and stable. Update frontend/mobile consumers
  when a contract changes.
- Avoid N+1 queries and unbounded list queries. Use the established pagination
  and ordering conventions where applicable.

## Verification

From `hostelcare-backend/`, use:

```bash
npm run typecheck
npm run build
```

Use `npm run test:isolation`, `npm run smoke`, and
`npm run audit:permissions` when the relevant database environment is available.
Do not run migrations or destructive database operations against shared data
without explicit user approval.

Do not claim runtime behavior was verified if only TypeScript compilation ran.
