docs: IntakeGateway/QueryGateway consolidation assessment and plan

[badry-dev]

Adds two documents assessing whether QueryGateway and IntakeGateway should be combined under one product, and what that would involve. Both are committed to IntakeGateway on the matching branch as well.

docs/tech-stack-comparison.md — should they be combined?

• Stack comparison — backend runtime, frontend, quality gates, and container topology, side by side.
• Shared surface — the ~9 capability areas both projects implement independently (connection registry, credential encryption, scheduling, run history, admin identity, settings/health, Oracle introspection, SPA shell, API client).
• Conflicts ranked by cost — Python 3.11 vs 3.14 (with a queue-on-3.14 blocker underneath), sync vs async SQLAlchemy, SQLite+create_all vs PostgreSQL+Alembic, Ant Design vs Tailwind/shadcn, incompatible auth models, config collision, route namespaces, loguru vs structlog, encrypted-file vs database credential storage.
• Recommendation — converge onto this repository's platform (async SQLAlchemy, PostgreSQL, structlog, JWT auth, Tailwind/shadcn, strict mypy plus bandit rules and the six CI workflows, segmented container networks) and port IntakeGateway's domain logic and worker topology onto it. Monorepo with shared packages, one admin console, two backend deployables. Four costed alternatives.
• Open decisions requiring a human call — queue technology on 3.14, multi-user/RBAC, product naming, destination breadth, snapshot storage.

docs/consolidation-plan.md — what gets adopted from where

Module-by-module verdicts at implementation level, taking the better implementation regardless of which repo it lives in. Neither codebase wins across the board.

Where this repository's implementation wins: the declarative base and PK strategy, BaseCrudRepository, global exception handlers, the pure-ASGI correlation middleware, Alembic-only migrations, container topology, JWT identity, per-endpoint auth policies, structlog, the read-side SQL executor with per-endpoint dynamic Pydantic models, schedule semantics and run preview, snapshot caching and coverage checking, the health dashboard, and on the frontend the shell, API client, useResourceMutations, and the wizard architecture.

Where IntakeGateway's implementation is adopted instead: the destination write path (batched binds, bulk upsert), the ingestion pipeline, SSRF protection (this repository has none), the OAuth2 token cache, rate-limit handling, cursor watermarks, the job queue (this repository has none), row-level error logging, schedule auto-pause after N consecutive failures, engine caching, log redaction, credential key rotation (rotate_key — this repository cannot rotate keys), Vite 8, and the coverage floor.

Notes specific to this repository:

• Async job execution is the one platform category where this repository has nothing. Long-running, retryable imports need a real queue, and scheduled snapshot refresh should move onto it too rather than running Oracle queries inside the API process.
• OracleConnection needs generalizing into a Connection with a db_type discriminator to absorb IntakeGateway's Oracle/PostgreSQL/MySQL breadth.
• oracledb major-version split across the two projects (>=4.0.2 here vs 3.4.2 there). This image already bundles Instant Client 19.32, which satisfies oracledb 4.x thick mode.
• Neither project supports multiple users or RBAC. If the combined product needs it, building it once during the identity-unification phase is materially cheaper than retrofitting later.

The document also recalibrates the phase estimates for AI-assisted development, where review throughput rather than code production is the binding constraint, and notes which parts of the work do not compress at all.

Changes

Documentation only. No code, dependency, or configuration changes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01L6oCRzNahV9djmgUtpNe9q

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}