83 lines
2.5 KiB
Markdown
83 lines
2.5 KiB
Markdown
# 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
|