Remix Framework + Oracle DB + Kinde Auth + SQLAlchemy via Bridge | CLAUDE.md Template

Overview

This page provides a copyable CLAUDE.md template for configuring a Remix Framework project that uses Oracle DB, Kinde Auth, and SQLAlchemy via a bridge. It’s tailored to a full-stack setup where Remix handles the UI and routes, a bridge service translates SQLAlchemy calls to Oracle queries, and Kinde provides identity and access management. Use this CLAUDE.md Template to bootstrap a production-ready configuration for Claude Code in this stack.

When to Use This CLAUDE.md Template

• You are building a Remix application that must connect securely to Oracle DB from a bridge layer using SQLAlchemy models.
• You require OAuth/OpenID Connect-based authentication via Kinde across routes with proper session handling.
• You want a copyable CLAUDE.md Template to guide project setup, security rules, and deployment considerations.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
- You are Claude Code, configured to bootstrap a Remix Framework + Oracle DB + Kinde Auth + SQLAlchemy via Bridge stack.
- You produce production-ready, secure, and auditable code artifacts and configuration blocks for the stack.

Architecture rules
- Remix route handlers call a bridge service that translates SQLAlchemy-like calls into Oracle SQL against an Oracle DB instance.
- SQLAlchemy is used as the ORM layer in the bridge service; the Remix app should never embed raw SQL strings directly.
- All credentials and secrets are read from environment variables and a dedicated secret store in the deployment environment.
- Authentication is managed by Kinde via OAuth 2.0 / OpenID Connect with PKCE for public clients.
- All external calls use TLS, and sensitive cookies are HttpOnly and Secure with SameSite=Lax or Strict.
- Telemetry and error logging are implemented with structured logs and error codes; errors should not leak sensitive details to clients.

File structure rules
- Keep Remix app code in remix-app/; place bridge logic in bridge/sqlalchemy_bridge/; place Oracle helpers in oracle/db_client/; store Kinde config under auth/kinde/
- Do not place SQL strings in client routes; keep them in the bridge module with parameterization.
- Use a single source of truth for config via environment variables and a config module.

Authentication rules
- Implement OAuth 2.0 / OpenID Connect with Kinde; use PKCE for the authorization code flow.
- Store user sessions in a server-side store and send a minimal session cookie to the client with HttpOnly and Secure attributes.
- Validate ID tokens and map claims to application roles with strict RBAC checks.

Database rules
- Connect to Oracle DB using a connection pool; never store DB credentials in code.
- Use parameterized queries; avoid string concatenation to prevent SQL injection.
- Map ORM models to SQL statements via SQLAlchemy bridging logic; ensure type-safe queries where possible.
- Implement transactions for multi-step operations and roll back on error.

Validation rules
- Validate all API inputs using a strict schema (e.g., Zod or a TS-first validation layer) before sending to the bridge.
- Normalize and sanitize outputs from the bridge before returning to clients.
- Ensure that null/undefined values are handled consistently and do not propagate to clients.

Security rules
- Enforce CSRF protection on state-changing endpoints.
- Use parameterized queries and ORM-level validations to avoid injection.
- Enforce least privilege DB roles; no broad SELECT permissions on production tables.
- Rotate credentials periodically and implement a credential rotator for Oracle DB access.
- Scan dependencies for known CVEs and use package lockfiles with pinned versions.

Testing rules
- Unit tests for the bridge SQLAlchemy adapters and Oracle client wrappers.
- Integration tests for remote Oracle DB calls using a test database or containerized Oracle instance.
- End-to-end tests that cover sign-in, data fetch, and data mutation flows.
- CI should run linting, type checks, tests, and security scans.

Deployment rules
- Containerize Remix app and bridge service; orchestrate with a simple YAML (Docker Compose) or a minimal Kubernetes manifest.
- Use environment-specific config (e.g., .env.local, .env.production) loaded securely by the app.
- Run DB migrations via a controlled process; do not auto-migrate in production without review.
- Ensure backups for Oracle DB and implement a disaster recovery plan.

Things Claude must not do
- Do not bypass Kinde OAuth flow or issue tokens without verification.
- Do not interpolate user input into SQL strings; always parameterize.
- Do not embed plaintext secrets in code or repository.
- Do not bypass bridge translation for SQLAlchemy by issuing raw Oracle calls from Remix routes.
- Do not expose internal bridge endpoints to the public internet without authentication.

Recommended Project Structure

RemixOracleBridge/
├─ remix-app/
│  ├─ app/
│  │  ├─ routes/
│  │  │  ├─ index.tsx
│  │  │  ├─ api/
│  │  │  └─ auth/
│  │  ├─ components/
│  │  ├─ entry.client.tsx
│  │  └─ entry.server.tsx
│  ├─ package.json
│  ├─ tsconfig.json
│  └─ remix.config.js
├─ bridge/
│  └─ sqlalchemy_bridge/
│     ├─ bridge.py
│     └─ requirements.txt
├─ oracle/
│  └─ db_client/
│     └─ oracle_client.py
├─ auth/
│  └─ kinde/
│     ├─ oauth_config.json
│     └─ kin_deploy_notes.md
└─ docker/
   ├─ Dockerfile
   └─ docker-compose.yml

Core Engineering Principles

• Security by default: enforce least privilege, secret management, and secure defaults everywhere.
• Type safety and input validation across API boundaries.
• Clear separation of concerns: Remix UI, bridge service, and database access are decoupled.
• Idempotent and auditable deployments with versioned configs and migrations.
• Observability: structured logging, tracing, and metrics for performance and security gaps.

Code Construction Rules

• All DB access happens through the bridge using SQLAlchemy models, not inline SQL in Remix routes.
• Environment variables are the exclusive source of configuration for credentials and endpoints.
• All inputs are validated against a typed schema; outputs are sanitized before sending to clients.
• Queries are parameterized; never interpolate user input into SQL strings.
• Handle transactions carefully: commit on success, rollback on error.
• Use PKCE in OAuth flows; verify ID tokens and map claims to roles securely.

Security and Production Rules

• Cookies: HttpOnly, Secure, SameSite=Strict for session cookies.
• CSRF protections on state-changing endpoints; use anti-forgery tokens where applicable.
• Oracle credentials stored securely; rotate regularly; access controlled by RBAC.
• TLS for all external communication; no plaintext traffic between services.
• Regular dependency scanning and patching; pin dependency versions.
• Limit exposure of bridge endpoints; require authentication for access.

Testing Checklist

• Unit tests for bridge adapters and Oracle client wrappers.
• Integration tests for bridge-to-Oracle interactions with a test DB.
• End-to-end tests covering login, data fetch, and mutation flows.
• Static analysis and type checks in CI; run security scanners.
• Smoke tests in staging before production deploys.

Common Mistakes to Avoid

• Hardcoding secrets or credentials in code or config files checked into VCS.
• Directly embedding SQL in Remix routes instead of using the bridge.
• Ignoring PKCE or token validation in Kinde OAuth flows.
• Using non-parameterized queries leading to SQL injection risks.
• Skipping monitoring; deploying without health checks or observability hooks.

FAQ

• What is this CLAUDE.md Template for? It provides a copyable configuration blueprint for Remix + Oracle DB + Kinde + SQLAlchemy via Bridge using Claude Code.
• Can I adapt this for other Oracle setups? Yes; the bridge and config blocks are stack-specific but designed to be customized for different Oracle schemas and environments.
• How do I run the bridge locally? Start the Remix app and the bridge service in separate containers or processes; ensure Oracle DB is reachable and environment variables are set.
• How is auth handled? Kinde OAuth/OpenID Connect is used; PKCE is enforced for public clients and ID tokens are validated on receipt.
• How do I deploy securely? Use TLS, secret stores, restricted network access, and migrations with versioned deployment pipelines.