Database and Related Services

Last synthesized: April 2026
Operational source: RapidDraft database, collaboration, Railway, backup, and embedding architecture discussion
Purpose: Give implementation agents the minimum collaboration infrastructure target while preserving the future service shape for backups, embeddings, and searchable model intelligence.

Decision Summary

RapidDraft's immediate collaboration rollout should use Railway as the hosted runtime surface:

• Railway app service for the current RapidDraft API and UI
• Railway Postgres as the primary shared database
• Stytch for product authentication, validated by the backend
• Railway persistent storage or object storage for CAD artifacts
• a later Railway worker for embeddings and indexing
• a backup job that writes encrypted database dumps to IONOS, SST/object storage, or another offsite target

This page intentionally avoids a self-hosted Supabase plan. Supabase is not part of the current collaboration deployment decision. The goal is to make a professional shared-review product work now without blocking future backup, embedding, and database-service expansion.

Minimum Collaboration Slice

The minimum setup for a real user to collaborate on a STEP model is:

Capability	Required now	Notes
Authentication	Yes	Use Stytch to identify users. The backend must validate sessions/JWTs and map them into local user records.
Shared database	Yes	Use Railway Postgres. Comments, replies, users, permissions, model records, and share links must not remain only in local JSON files.
File persistence	Yes	STEP files, previews, PDFs, screenshots, and generated scene artifacts need durable storage outside Postgres.
Share links	Yes	Use app-level share tokens with view/comment/edit grants. Do not expose the database directly.
Authorization checks	Yes	Every model-scoped read/write must check owner, explicit grant, or valid share-link permission.
Comment persistence	Yes	The current comment UI is useful; the persistence layer must become database-backed so comments survive deploys and are shared across users.
Embedding worker	No	Keep the schema compatible, but do not block collaboration rollout on semantic search.
Backup job	Strongly recommended	A pilot can start with a simple nightly pg_dump, but real users should not be invited without at least one offsite backup path.

Service Boundary

The immediate deployment should keep the service boundaries simple:

Browser
  |
  | Stytch login/session
  v
Railway RapidDraft app
  |
  | private database connection
  v
Railway Postgres + pgvector-ready schema
  |
  | async jobs later
  v
Railway embedding worker

Backup job
  |
  | encrypted dumps
  v
IONOS / SST / object storage

The database is the product source of truth. The app owns authentication, authorization, share-link resolution, and business rules. Users should never connect to Postgres directly.

Database Responsibilities

Railway Postgres should own the durable collaboration state:

• organizations and organization membership
• users mapped from Stytch identities
• projects or workspaces
• model documents and model revisions
• uploaded model file metadata
• comments, replies, review sessions, assignments, statuses, and resolved state
• share links and explicit access grants
• activity events for recovery and audit context
• embedding jobs and embedding item metadata when the embedding service is added

The existing repo uses per-model files such as reviews.json for comments and design reviews. That is acceptable for a local prototype, but the collaboration deployment should migrate the shared collaboration state into Postgres.

Artifact Storage Responsibilities

Postgres should not store large CAD binaries or generated media. It should store stable metadata, checksums, permissions, and URLs/keys.

Artifact storage should own:

• original STEP/STP files
• generated GLB previews
• canonical scene JSON and per-component scene detail
• DFM PDFs and other exports
• screenshots and comment attachments
• large scanner artifacts when they become too bulky for database rows

For the minimum Railway rollout, a persistent Railway volume can be acceptable if deployment velocity matters. For a more durable production path, prefer S3-compatible object storage such as Cloudflare R2 or another object store, with Postgres rows pointing to object keys.

Authentication and Authorization

Stytch should be used for product authentication. The backend should translate a validated Stytch identity into a RapidDraft user record and then enforce access through database records.

The minimum access model is:

Role	View	Comment	Edit review state	Manage sharing
Owner	Yes	Yes	Yes	Yes
Editor	Yes	Yes	Yes	No
Commenter	Yes	Yes	No	No
Viewer	Yes	No	No	No

Share links should be app-level links such as /share/{token}. Store only a token hash in Postgres. A share link should carry an access level, expiration, revocation state, and optional email/domain restriction.

Future Embedding Service

The first collaboration rollout does not need embeddings. It should still avoid design choices that make embeddings hard later.

The future embedding service should be a separate Railway worker that reads queued jobs from Postgres, computes text/image/model-context embeddings, and writes vectors or vector metadata back to Postgres.

Candidate embedding sources:

• MECRI or manufacturing-rule text
• DFM finding summaries
• Part Facts summaries
• review comments and decisions
• screenshot captions from vision models
• model/revision metadata

Use pgvector in Railway Postgres first. A specialist vector database should be considered only after pgvector becomes a measured bottleneck.

Backup Service

The backup service is related but not required to sit in the same runtime as the app. The near-term backup design should be:

1. A scheduled Railway job runs pg_dump against Railway Postgres.
2. The dump is compressed and encrypted.
3. The encrypted dump is written to IONOS, SST/object storage, or another offsite target.
4. A restore test is run periodically into a temporary database.

IONOS is best treated as a backup destination at this stage, not the live production database host. That keeps pilot traffic inside Railway while still giving the team an independent recovery path.

Implementation Guardrails

Implementation agents working on the collaboration setup should preserve these guardrails:

• Do not build direct browser-to-database access.
• Do not store STEP/GLB/PDF/screenshots as large blobs in Postgres.
• Do not hard-code Railway-only assumptions into the schema; use ordinary Postgres migrations.
• Do not make embeddings a dependency for comments, model sharing, or login.
• Do not make the backup destination part of the request path.
• Keep every model-scoped write behind backend authorization checks.
• Use database migrations rather than manual one-off SQL when possible.

Recommended First Tables

A practical first schema can start with:

users
organizations
organization_members
projects
model_documents
model_revisions
model_artifacts
review_tickets
ticket_replies
design_reviews
share_links
model_access_grants
activity_events
embedding_jobs
embedding_items

embedding_jobs and embedding_items can be introduced as empty or deferred tables if the team wants the migration boundary ready before the embedding worker exists.

Open Questions

• Should the first external user receive authenticated invite access only, or should share links support unauthenticated view/comment access from day one?
• Should model artifacts initially stay on a Railway persistent volume, or should object storage be introduced before the first collaboration pilot?
• Should the backup job run inside Railway and push to IONOS, or run on IONOS and pull from Railway?
• Which Stytch mode is the final choice for the pilot: email magic links, B2B organization auth, or a simpler passwordless flow?
• Which rows must be migrated first from the current JSON stores to make the collaboration experience credible?

Sources

• Current repo reviewed: D:\02_Code\45_merged_macos_colabui_dfmanim
• Related wiki page: Collaboration Infrastructure
• Related repo contract: docs/contracts/pilot-access-session.md
• Current backend file persistence entry point: server/storage_paths.py
• Current model metadata store: server/model_store.py
• Current comment/review store: server/review_store.py
• Current Part Facts and geometry artifact cache direction: server/part_facts.py