# AGENTS.md

This file is the operational guide for coding agents working in this repository.
It reflects the codebase as it exists now.

## Project Reality

- App type: Fresh 2 + Deno full-stack web app
- Domain: landlord/tenant rental workflows + financial calendar
- Primary database: PostgreSQL through Drizzle (`db/schema.ts`, `db/db.ts`)
- Cache/state bridge: `modules/KvCacheStore.ts` (memory/file KV with SQL
  synchronization)
- Auth model: OAuth login/callback with encrypted session cookies

## Core Paths

- `main.ts`: app bootstrap, middleware wiring, health/debug endpoints
- `routes/`: page routes and API endpoints
- `services/`: business logic, route auth/role guard, domain services
- `db/`: schema and SQL repository methods
- `modules/KvCacheStore.ts`: KV facade + SQL write-through for user/session data
- `tests/`: Playwright E2E and integration coverage

## Required Environment

Required for normal auth + data flow:

- `POSTGRES_OPTIONS`
- `AUTHORITY`
- `CLIENT_ID`
- `CLIENT_SECRET`
- `REDIRECT_URI`
- `TOKEN_URL`
- `REDIRECT_HOME`

Frequently used optional vars:

- `PORT`, `HOSTNAME_DENO`, `DEVELOPMENT`
- `SANDBOX_MODE`, `DISABLE_EXTERNAL_APIS`
- `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_PUBLISHABLE_KEY`
- `KV_CACHE_PATH`

## Commands You Should Use

- Start dev server: `deno task dev`
- Build: `deno task build`
- Start production build: `deno task start`
- Full checks: `deno task check`
- E2E tests: `deno task e2e`
- Auth callback DB regression: `deno task test:auth-callback-db`

Per-file validation during edits:

- `deno check <file>`
- `deno fmt <file>`
- `deno lint <file>`

## Auth/DB Invariants (Do Not Break)

- Keep `search_path` with `public` first (`db/db.ts`).
- Upsert/ensure `users` row before writing `user_tokens` in auth callback flow.
- Preserve concurrent-session behavior: `user_tokens` keyed by
  `(user_id, state_id)`.
- Keep session cookie seal/unseal compatible with `state_keys` persistence.

## Editing Expectations

- Prefer TypeScript for any new code.
- Keep route protections aligned with `services/authRouteConfig.ts`.
- If you add/rename API routes, update tests in `tests/e2e`.
- If you modify auth/session behavior, run at least:
  - `deno task check`
  - `deno task test:auth-callback-db`

## Outdated Docs Cleanup Policy

Do not add one-off session summaries or temporary feature-verification markdown
files at the project root. Keep permanent documentation in:

- `README.md` for project usage
- `AGENTS.md` for contributor/agent runbook
- `CLAUDE.md` for deep troubleshooting and invariants