Entity Relations — MongoDB

Visual reference for all MongoDB collections, their schemas, and their cross-references to PostgreSQL.

Full collection schemas (indexes, TTLs, security): mongo.md

MongoDB does not enforce foreign key constraints. All references to PostgreSQL records are maintained by application logic. References use PostgreSQL ref_id (ULID) values unless otherwise noted.

Collections Overview

Rendering diagram…

Cross-References: MongoDB → PostgreSQL

Each MongoDB collection references one or more PostgreSQL records. These are application-level references — no DB-enforced constraint.


MongoDB                          PostgreSQL
─────────────────────────────────────────────────────
activity_outputs
  .activityId          ──────→  activities.ref_id
  .activityRunId       ──────→  activity_runs.ref_id

activity_streams
  .activityId          ──────→  activities.ref_id

event_logs
  .activityId          ──────→  activities.ref_id
  .goalId              ──────→  goals.ref_id

onboarding_research
  .runId               ──────→  onboarding_runs.ref_id

strategies_content
  .strategyId          ──────→  strategies.ref_id

tool_call_logs
  .toolCallId          ──────→  tool_calls.ref_id
  .activityRunId       ──────→  activity_runs.ref_id

skills
  (tenantId only — no FK to a specific record)

audit_logs
  .resourceId          ──────→  any table ref_id (polymorphic)

Cross-References: MongoDB → S3

MongoDB documents that hold large content store S3 keys — the actual bytes are in S3.


MongoDB                          S3 key
─────────────────────────────────────────────────────────────────────────
activity_outputs
  .s3Key               ──────→  {tenantId}/activity-outputs/{activityId}/{refId}.{ext}

onboarding_research
  .websiteTextS3Key    ──────→  {tenantId}/onboarding/{runId}/website-text.txt
  .competitorResearchS3Key ──→  {tenantId}/onboarding/{runId}/competitor-research.txt
  .industryContextS3Key ─────→  {tenantId}/onboarding/{runId}/industry-context.txt
  .rawNotesS3Key       ──────→  {tenantId}/onboarding/{runId}/raw-notes.txt
  .generatedContextFileS3Key →  {tenantId}/onboarding/{runId}/context-file.md

strategies_content
  .s3Key               ──────→  {tenantId}/strategies/{strategyId}/v{version}.md

Cross-References: PostgreSQL → MongoDB

PostgreSQL stores MongoDB ObjectIds as VARCHAR(24) reference pointers.


PostgreSQL                       MongoDB
─────────────────────────────────────────────────────
activities.output_ref  ────────→  activity_outputs._id
blog_posts.content_ref ────────→  activity_outputs._id
social_posts.content_ref ──────→  activity_outputs._id
onboarding_runs
  .context_file_id     ────────→  skills._id (and onboarding_research._id)

Cross-References: PostgreSQL → S3 (direct)

The contracts table holds the S3 key directly — no MongoDB intermediary needed for contract PDFs.


PostgreSQL                       S3 key
─────────────────────────────────────────────────────────────────────────
contracts.pdf_s3_key   ────────→  {tenantId}/contracts/{contractRefId}/v{templateVersion}.pdf

Note: strategies_content is referenced by strategies.ref_id stored inside the MongoDB document itself (not a column in PostgreSQL’s strategies table — the strategy row is looked up by strategyId within the MongoDB document).

TTL Summary

Collection	MongoDB TTL	S3 content TTL	Notes
`activity_outputs`	None — permanent	None — permanent	Client-facing content; S3 content retained indefinitely
`activity_streams`	24 hours	—	Transient streaming buffer; no S3 content
`skills`	None — permanent	—	Full text in MongoDB; full-text search required
`audit_logs`	None — permanent	—	Compliance; retained minimum 2 years
`event_logs`	90 days	—	Operational log, no S3 content
`onboarding_research`	None — permanent	None — permanent	Metadata in MongoDB; research text in S3
`strategies_content`	None — permanent	None — permanent	Pointer in MongoDB; full Markdown in S3
`contract_pdfs`	Eliminated	None — permanent	S3 with Object Lock (WORM) on contracts prefix
`tool_call_logs`	90 days	—	Small JSON payloads stay in MongoDB

Tenant Scoping

Every collection is scoped by tenantId. The only exception is skills with tenantId: 'global' for platform-wide default skill files.

Collection	tenantId values
`activity_outputs`	tenant `ref_id`
`activity_streams`	tenant `ref_id`
`skills`	tenant `ref_id` OR `'global'`
`audit_logs`	tenant `ref_id` OR `null` (platform-level actions)
`event_logs`	tenant `ref_id`
`onboarding_research`	tenant `ref_id`
`strategies_content`	tenant `ref_id`
`contract_pdfs`	tenant `ref_id`
`tool_call_logs`	tenant `ref_id`

Collection Relationships Within MongoDB

MongoDB collections do not reference each other directly. All cross-collection relationships go through PostgreSQL as the source of truth.

The one implicit relationship is between onboarding_research and skills:

The Onboarding Agent writes its generatedContextFile both to onboarding_research.generatedContextFile (raw research output) and creates a separate document in skills (the injected context file).
onboarding_runs.context_file_id in PostgreSQL points to the skills document.