docs(mongodb): choose trusted runtime topology
This commit is contained in:
parent
e8f2ea3d11
commit
44c3ca4c93
2 changed files with 203 additions and 1 deletions
|
|
@ -0,0 +1,177 @@
|
|||
# V1 ADR 003: MongoDB Runtime Topology
|
||||
|
||||
Status: Accepted during Block 16.1
|
||||
|
||||
Date: 2026-06-25
|
||||
|
||||
## Context
|
||||
|
||||
MongoDB is the committed persistence target for V1, but the Flutter UI and pure
|
||||
Dart scheduling core must not own production database credentials. Block 15
|
||||
completed the adapter-neutral document schema, codecs, repository contracts,
|
||||
index catalog, payload limits, and migration contracts.
|
||||
|
||||
Before adding a MongoDB dependency, Block 16 needs a runtime decision that keeps
|
||||
credentials inside a trusted boundary, supports transactions, and avoids
|
||||
deprecated MongoDB client-access products.
|
||||
|
||||
Sources checked on 2026-06-25:
|
||||
|
||||
- MongoDB official client libraries list:
|
||||
`https://www.mongodb.com/docs/drivers/`
|
||||
- MongoDB Node.js driver docs:
|
||||
`https://www.mongodb.com/docs/drivers/node/current/`
|
||||
- MongoDB Node.js transaction docs:
|
||||
`https://www.mongodb.com/docs/drivers/node/current/crud/transactions/`
|
||||
- MongoDB transaction manual:
|
||||
`https://www.mongodb.com/docs/manual/core/transactions/`
|
||||
- MongoDB Atlas App Services EOL notice:
|
||||
`https://www.mongodb.com/docs/api/doc/atlas-app-services-admin-api-v3/`
|
||||
- Deprecated Atlas Data API docs:
|
||||
`https://www.mongodb.com/docs/api/doc/atlas-data-api-v1/`
|
||||
- Dart package checks:
|
||||
`https://pub.dev/packages/mongo_dart` and
|
||||
`https://pub.dev/packages/mongo_db_driver`
|
||||
|
||||
## Decision
|
||||
|
||||
V1 selects a trusted service boundary for MongoDB persistence.
|
||||
|
||||
The MongoDB-owning runtime is a separate Node.js/TypeScript service using the
|
||||
official MongoDB Node.js driver. This service owns:
|
||||
|
||||
- MongoDB connection strings and credentials;
|
||||
- TLS/SRV driver configuration;
|
||||
- client lifecycle and health checks;
|
||||
- index bootstrap from the Block 15 index catalog;
|
||||
- document reads/writes against the V1 collection contract;
|
||||
- sessions and transactions for multi-record scheduling writes;
|
||||
- redacted diagnostics and failure mapping.
|
||||
|
||||
The Flutter UI never connects directly to MongoDB and never receives connection
|
||||
strings, database credentials, raw MongoDB documents, driver clients,
|
||||
collections, sessions, or cursors.
|
||||
|
||||
The pure Dart package remains dependency-free with respect to MongoDB. Dart
|
||||
domain and application code continue to use repository interfaces and typed use
|
||||
case results. The trusted service exposes a narrow versioned application API
|
||||
that maps to the Block 14 use cases and Block 15 document contract.
|
||||
|
||||
During the UI foundation/design spike, the first Flutter UI should use the
|
||||
existing in-memory application composition by default. Persisted development
|
||||
flows may use a local trusted service process, but that process remains outside
|
||||
the Flutter binary and reads secrets only from runtime configuration.
|
||||
|
||||
## Rejected Options
|
||||
|
||||
### Direct MongoDB from Flutter or mobile Dart
|
||||
|
||||
Rejected. It would place database credentials in an untrusted binary and force
|
||||
the UI to own network/database failure modes. It also couples the UI to driver
|
||||
types and makes owner-scope/security mistakes harder to contain.
|
||||
|
||||
### Pure Dart MongoDB adapter as the production V1 foundation
|
||||
|
||||
Rejected for now. MongoDB's official client library list does not include Dart.
|
||||
`mongo_dart` is active and useful for experiments, but it is community-supported
|
||||
rather than an official MongoDB driver. `mongo_db_driver` advertises sessions and
|
||||
transactions, but its package page explicitly identifies it as pre-alpha and not
|
||||
suitable for production. Neither should become the V1 persistence foundation
|
||||
without a later ADR reversing this decision.
|
||||
|
||||
### Atlas Data API, Atlas Device SDKs, App Services, GraphQL, Functions, or
|
||||
Custom HTTPS Endpoints
|
||||
|
||||
Rejected. MongoDB's App Services notice says these paths reached end-of-life on
|
||||
September 30, 2025, with database triggers remaining available. They are not a
|
||||
stable V1 foundation.
|
||||
|
||||
### SQLite or another local fallback
|
||||
|
||||
Rejected. MongoDB remains the committed persistence target. A disconnected
|
||||
fallback would add an unplanned sync/reconciliation problem and violate the
|
||||
current persistence target rules.
|
||||
|
||||
## Driver and Deployment Requirements
|
||||
|
||||
The selected service must use the official MongoDB Node.js driver current major
|
||||
line at implementation time.
|
||||
|
||||
Mandatory capabilities:
|
||||
|
||||
- `mongodb+srv://` and TLS-capable connections for Atlas;
|
||||
- BSON fidelity at the adapter edge;
|
||||
- sessions and multi-document transactions;
|
||||
- explicit transaction retry handling for documented retryable categories;
|
||||
- bounded connection and operation timeouts;
|
||||
- graceful startup/shutdown and health checks;
|
||||
- idempotent index creation;
|
||||
- redacted logging;
|
||||
- no raw driver values in public service DTOs.
|
||||
|
||||
MongoDB deployment requirements:
|
||||
|
||||
- Multi-document scheduling writes require MongoDB Server 4.0 or later.
|
||||
- Transaction acceptance requires a transaction-capable deployment. V1 local and
|
||||
CI testing must use a replica set or supported sharded deployment, not a
|
||||
standalone server.
|
||||
- If the service cannot verify transaction capability at startup for a
|
||||
production Mongo-backed configuration, it must fail closed instead of falling
|
||||
back to untracked in-memory writes.
|
||||
|
||||
## Configuration Boundary
|
||||
|
||||
Development configuration:
|
||||
|
||||
- Uses environment variables or a local secret file excluded from git.
|
||||
- May point to a disposable local replica set or scoped Atlas development
|
||||
database.
|
||||
- Must use a database name or prefix that is safe for destructive test cleanup.
|
||||
|
||||
Test configuration:
|
||||
|
||||
- Uses uniquely named disposable databases/collections.
|
||||
- Fails if the configured target does not match the expected test scope.
|
||||
- Redacts connection strings and credentials from test output.
|
||||
|
||||
Production configuration:
|
||||
|
||||
- Secrets come from deployment secret storage.
|
||||
- The Flutter/mobile app receives only service endpoint configuration and
|
||||
application-layer auth/session material once that future work is explicitly
|
||||
planned.
|
||||
- Production authentication, account management, cross-device sync, Atlas
|
||||
provisioning, network allowlists, and cluster creation remain out of scope for
|
||||
this block.
|
||||
|
||||
## Threat and Safety Checklist
|
||||
|
||||
- No MongoDB connection string is committed to source control.
|
||||
- No MongoDB credential is embedded in Flutter, mobile, desktop, or web UI
|
||||
assets.
|
||||
- Normal logs do not include task titles, hidden locked-block names, full
|
||||
documents, connection strings, or credential fragments.
|
||||
- Every repository query and write includes owner scope.
|
||||
- Hidden locked-time details remain hidden by default in service responses.
|
||||
- Duplicate operation IDs are enforced by a unique owner-operation index.
|
||||
- Revision predicates are required for authoritative updates.
|
||||
- Transaction retries are bounded and observable.
|
||||
- A production Mongo connection failure fails closed.
|
||||
- In-memory composition remains available only as explicit local/design-spike
|
||||
wiring, not as a silent production persistence fallback.
|
||||
|
||||
## Consequences
|
||||
|
||||
Block 16.2 must add any MongoDB dependency only in the trusted service/runtime
|
||||
module, not in the pure Dart core package.
|
||||
|
||||
The implementation path should provide two composition roots:
|
||||
|
||||
- in-memory Dart application wiring for tests and UI design work;
|
||||
- trusted service-backed persistence for MongoDB-backed development and future
|
||||
deployment.
|
||||
|
||||
If a later chunk cannot implement the selected service boundary without
|
||||
duplicating scheduling rules unsafely, it must stop and record the blocker
|
||||
rather than embedding credentials in Flutter or adopting an unmaintained driver
|
||||
as a shortcut.
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# V1 Block 16 — MongoDB Runtime Adapter and Transaction Boundary
|
||||
|
||||
Status: Planned
|
||||
Status: In progress
|
||||
|
||||
Purpose: Implement the committed MongoDB persistence target behind the completed
|
||||
repository/application contracts while keeping credentials out of Flutter and
|
||||
|
|
@ -10,6 +10,8 @@ making multi-record scheduling operations safe.
|
|||
|
||||
Recommended Codex level: extra high
|
||||
|
||||
Status: Complete
|
||||
|
||||
Tasks:
|
||||
|
||||
- Re-check current official MongoDB driver support, transaction requirements,
|
||||
|
|
@ -54,6 +56,29 @@ Acceptance criteria:
|
|||
- A threat/configuration checklist exists.
|
||||
- No database package or credentials were added before this decision.
|
||||
|
||||
Completed implementation:
|
||||
|
||||
- Re-checked current MongoDB official driver, transaction, and App Services
|
||||
deprecation documentation on 2026-06-25.
|
||||
- Added `V1_ADR_003_MongoDB_Runtime_Topology.md`.
|
||||
- Selected a trusted Node.js/TypeScript service boundary using the official
|
||||
MongoDB Node.js driver for the MongoDB-owning runtime.
|
||||
- Explicitly rejected direct MongoDB access from Flutter/mobile binaries,
|
||||
production use of current Dart community MongoDB drivers, deprecated Atlas
|
||||
Data API/App Services/Device SDK paths, and non-MongoDB persistence fallbacks.
|
||||
- Defined credential ownership, UI connection path, local/test/production
|
||||
configuration boundaries, deployment transaction requirements, and a
|
||||
threat/safety checklist.
|
||||
- Kept the pure Dart package free of MongoDB dependencies and did not add
|
||||
credentials, connection strings, Atlas setup, accounts, sync, or provisioning.
|
||||
|
||||
Verification:
|
||||
|
||||
- `dart format lib test`: passed, 0 files changed
|
||||
- `dart analyze`: passed, no issues found
|
||||
- `dart test`: passed, 298 tests
|
||||
- `git diff --check`: passed
|
||||
|
||||
BREAKPOINT: Stop here. Review and accept the runtime topology ADR before adding a
|
||||
MongoDB dependency, even if the Codex level remains `extra high`.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue