# CyberHybridHub

CyberHybridHub is a Fresh + Deno web application for rental operations and
financial calendar workflows.

## Current Stack

- Runtime: Deno
- Framework: Fresh 2 + Vite + Preact
- Data: PostgreSQL via Drizzle ORM
- Cache bridge: `modules/KvCacheStore.ts` (memory/file KV plus SQL
  write-through)
- Auth: OAuth callback flow (`/auth/login`, `/auth/callback`, `/auth/validate`)
- Payments: local sandbox mode or Stripe (depending on env flags)
- E2E: Playwright (`tests/e2e`)

## Product Areas Implemented

- Landlord portal: properties, leases, applications, maintenance, messaging,
  reminders, payments, documents, onboarding
- Tenant portal: dashboard, property, applications, maintenance, messaging,
  reminders, payments/payment methods, documents, settings
- Financial calendar: income and obligations pages
- API surface: CRUD endpoints under `routes/api/*`

## Repository Layout

- `routes/`: Fresh route handlers/pages and API endpoints
- `islands/`: interactive Preact islands
- `components/`: reusable UI components
- `services/`: business logic and route guards
- `db/`: Drizzle schema, DB connection, SQL repositories
- `modules/`: KV cache abstraction and SQL bridge
- `tests/`: Playwright E2E and integration tests
- `drizzle/`: generated Drizzle SQL artifacts

## Prerequisites

- Deno installed
- PostgreSQL running locally or remotely
- Environment file configured (`.env`)

## Environment Setup

1. Copy `.env.example` to `.env`.
2. Set `POSTGRES_OPTIONS` to a working PostgreSQL connection string.
3. Configure OAuth values used by auth routes:
   - `AUTHORITY`
   - `CLIENT_ID`
   - `CLIENT_SECRET`
   - `REDIRECT_URI`
   - `TOKEN_URL`
   - `REDIRECT_HOME`
4. Optional for payments:
   - `STRIPE_SECRET_KEY`
   - `STRIPE_WEBHOOK_SECRET`
   - `STRIPE_PUBLISHABLE_KEY`

## Local Development

```bash
deno task dev
```

Default host/port are controlled by:

- `HOSTNAME_DENO` (defaults via config)
- `PORT` (default `8080`)

## Build and Run

```bash
deno task build
deno task start
```

## Quality Checks

```bash
deno task check
```

Per-file checks during edits:

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

## Database Tasks

```bash
deno task db:generate
deno task db:migrate
deno task db:push
deno task db:studio
```

## Tests

```bash
deno task e2e
deno task e2e:ui
deno task e2e:report
deno task test:auth-callback-db
```

Notes:

- `tests/run-auth-callback-db-test.sh` wraps the auth callback DB regression
  test and performs cleanup on exit.
- Health endpoint: `GET /health`.
- Schema debug endpoint: `GET /api/debug/schema`.

## Auth and Session Notes

- Route protection is centralized in `services/authRouteConfig.ts` and
  `services/authMiddleware.ts`.
- Session cookies are sealed/unsealed with `iron`.
- Session and token state uses both KV and SQL persistence paths.

## Important Invariants

- `db/db.ts` sets `search_path` to `public, memory, checkpoints`.
- Auth callback must upsert user before token insert.
- `user_tokens` uses composite key `(user_id, state_id)` to support concurrent
  sessions.