integratedhub/CLAUDE.md

CyberHybridHub Runbook

This is a focused runbook for working safely in the current CyberHybridHub codebase.

1. Architecture Snapshot

• Framework: Fresh 2 with Vite (main.ts)
• Server runtime: Deno
• Persistence: PostgreSQL + Drizzle (db/schema.ts, db/db.ts)
• Supplemental cache layer: modules/KvCacheStore.ts
• Authentication:
  • /auth/login starts OAuth flow
  • /auth/callback exchanges code, upserts user, stores tokens, sets cookies
  • /auth/validate refreshes token/session
• Authorization: services/authMiddleware.ts + services/authRouteConfig.ts

2. Critical Invariants

• Database search path must keep public first: SET search_path TO public, memory, checkpoints.
• OAuth callback must guarantee parent users row exists before writing to user_tokens.
• Concurrent session support depends on composite key (user_id, state_id) in user_tokens.
• Cookie sealing/unsealing must stay compatible with state_keys records.

If these drift, auth failures and FK errors are likely.

3. High-Risk Files

• routes/auth/callback.ts
• routes/auth/validate.ts
• services/stateMiddleware.ts
• services/authMiddleware.ts
• db/db.ts
• db/sqlUserRepository.ts
• modules/KvCacheStore.ts

4. Local Setup Checklist

1. Copy .env.example to .env.
2. Set POSTGRES_OPTIONS.
3. Set OAuth env vars (AUTHORITY, CLIENT_ID, CLIENT_SECRET, REDIRECT_URI, TOKEN_URL, REDIRECT_HOME).
4. Start app: deno task dev.

5. Verification Commands

Baseline quality:

deno task check

Auth callback regression:

deno task test:auth-callback-db

E2E suite:

deno task e2e

6. Troubleshooting

FK error on token insert

Symptom:

• foreign key violation for user_tokens_user_id_users_id_fk

Checks:

1. Confirm callback still upserts/ensures user before token write.
2. Confirm writes target expected schema/tables.
3. Confirm POSTGRES_OPTIONS points to the intended database.
4. Restart server to avoid stale process code paths.

Session appears invalid after login

Checks:

1. Verify xx_state_id and session cookies are both present.
2. Confirm state_keys row exists for the same state ID.
3. Ensure cookie hash/state key validation logic remains unchanged.

Payments in local mode

• If SANDBOX_MODE=true or DISABLE_EXTERNAL_APIS=true, payment intent flow stays local and does not call Stripe.

Islands disappear after load (production / Ubuntu server)

Symptom:

• Island components (e.g. WelcomeBar, GuestHome) render briefly then vanish when the app is run from a production build on another machine (e.g. Ubuntu).

Cause:

• Multiple copies of Preact end up in the bundle/cache. Hydration then fails and Preact can tear down the island DOM. Common when the server has a different or stale Deno cache than the machine that built the app.

Checks and fix:

1. On the deployment server (Ubuntu), force a clean dependency install before building:

   deno install -r --allow-scripts
   deno task build
   deno task start
   

2. Ensure the process working directory is the project root so that _fresh/server.js and _fresh/static/ are found (e.g. in systemd set WorkingDirectory= to the app directory).

3. For reproducible builds across machines, consider re-enabling the lockfile in deno.json ("lock": true) and committing deno.lock, then using the same lock on the server.

4. Do not use esm.sh for Preact (this project already uses npm:preact); duplicate Preact from mixed sources is a common cause.

7. Change Discipline

• Keep docs and code aligned when behavior changes.
• Avoid adding temporary root-level feature summary markdown files.
• After auth/session/database changes, always run:
  • deno task check
  • deno task test:auth-callback-db