integratedhub/AGENTS.md

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