129 lines
3.0 KiB
Markdown
Executable File
129 lines
3.0 KiB
Markdown
Executable File
# 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.
|