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

deno task dev

Default host/port are controlled by:

• HOSTNAME_DENO (defaults via config)
• PORT (default 8080)

Build and Run

deno task build
deno task start

Quality Checks

deno task check

Per-file checks during edits:

deno check <file>
deno fmt <file>
deno lint <file>

Database Tasks

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

Tests

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.