Skip to main content

Context Sync Workflows

Architecture Reference: ADR-044 (Custom REST Sync), ADR-045 (Team/Project Context Sync) Version: 1.0.0 Last Updated: December 30, 2025

Overview​

This document defines H.P.006-WORKFLOWS for CODITECT's multi-level context synchronization system, enabling:

  • User-level sync - Personal context across devices (ADR-044)
  • Team-level sync - Shared team knowledge (ADR-045)
  • Project-level sync - Project-scoped insights (ADR-045)
  • Hierarchical backup - Multi-level backup to GCS (ADR-045)

Workflow Index​

IDNameTriggerPriority
WF-CS-001User Context PushDevice syncP0
WF-CS-002User Context PullDevice syncP0
WF-CS-003Team Context PushTeam member contributionP1
WF-CS-004Team Context PullTeam sync requestP1
WF-CS-005Project Context PushProject contributionP1
WF-CS-006Project Context PullProject sync requestP1
WF-CS-007Incremental BackupScheduled (hourly)P0
WF-CS-008Full BackupScheduled (daily)P1
WF-CS-009On-Demand BackupUser requestP2
WF-CS-010Backup RestoreUser requestP1
WF-CS-011Conflict ResolutionConcurrent writesP0
WF-CS-012Cursor ReconciliationSync driftP2

WF-CS-001: User Context Push​

Purpose: Push local context changes to cloud storage

Sequence Diagram​

Request/Response​

Request:

POST /api/v1/context/push
Authorization: Bearer <jwt>
X-Device-ID: device-uuid-123

{
  "messages": [
    {
      "type": "decision",
      "content": "Use PostgreSQL RLS for tenant isolation",
      "metadata": {
        "source": "session-abc",
        "timestamp": "2025-12-30T10:00:00Z"
      }
    }
  ]
}

Response:

{
  "synced": 1,
  "skipped": 0,
  "cursor": 12345,
  "timestamp": "2025-12-30T10:00:01Z"
}

WF-CS-002: User Context Pull​

Purpose: Pull context changes from cloud to local device

Sequence Diagram​

Request/Response​

Request:

GET /api/v1/context/pull?cursor=12340&limit=100
Authorization: Bearer <jwt>
X-Device-ID: device-uuid-123

Response:

{
  "messages": [
    {
      "id": "uuid-1",
      "type": "decision",
      "content": "Use PostgreSQL RLS for tenant isolation",
      "content_hash": "abc123...",
      "metadata": {},
      "created_at": "2025-12-30T10:00:00Z"
    }
  ],
  "cursor": 12345,
  "has_more": false
}

WF-CS-003: Team Context Push​

Purpose: Share context insights with team members

Sequence Diagram​

Permission Model​

RoleCan PushCan PullCan BackupCan Restore
Team Member✅✅❌❌
Team Admin✅✅✅✅
Team Owner✅✅✅✅

WF-CS-004: Team Context Pull​

Purpose: Retrieve shared team context

Request/Response​

Request:

GET /api/v1/teams/{team_id}/context/pull?cursor=0&limit=100
Authorization: Bearer <jwt>
X-Device-ID: device-uuid-123

Response:

{
  "messages": [
    {
      "id": "uuid-1",
      "type": "pattern",
      "content": "Always validate input at API boundaries",
      "contributed_by": "user-uuid-456",
      "created_at": "2025-12-30T09:00:00Z"
    }
  ],
  "cursor": 500,
  "has_more": false
}

WF-CS-005: Project Context Push​

Purpose: Share context insights within a project boundary

Permission Model​

RoleCan PushCan PullCan BackupCan Restore
Project Viewer❌✅❌❌
Project Member✅✅❌❌
Project Admin✅✅✅✅
Project Owner✅✅✅✅

WF-CS-007: Incremental Backup​

Purpose: Scheduled hourly incremental backup to GCS

Sequence Diagram​

GCS Path Structure​

gs://coditect-context-backups/
├── tenants/{tenant_id}/
│   ├── users/{user_id}/
│   │   ├── incremental/
│   │   │   ├── 2025-12-30-10.jsonl.gz
│   │   │   └── 2025-12-30-11.jsonl.gz
│   │   └── full/
│   │       └── 2025-12-30.jsonl.gz
│   ├── teams/{team_id}/
│   │   ├── incremental/
│   │   └── full/
│   └── projects/{project_id}/
│       ├── incremental/
│       └── full/

WF-CS-008: Full Backup​

Purpose: Scheduled daily full backup to GCS

Backup Metadata​

{
  "id": "uuid-backup-1",
  "tenant_id": "uuid-tenant",
  "scope_type": "team",
  "scope_id": "uuid-team",
  "backup_type": "full",
  "gcs_path": "gs://coditect-context-backups/tenants/.../full/2025-12-30.jsonl.gz",
  "size_bytes": 1048576,
  "record_count": 5000,
  "checksum": "sha256:abc123...",
  "status": "completed",
  "created_at": "2025-12-30T00:00:00Z",
  "completed_at": "2025-12-30T00:05:00Z",
  "expires_at": "2026-03-30T00:00:00Z"
}

WF-CS-010: Backup Restore​

Purpose: Restore context from a backup

Sequence Diagram​

Request/Response​

Request:

POST /api/v1/teams/{team_id}/context/restore
Authorization: Bearer <jwt>

{
  "backup_id": "uuid-backup-1",
  "mode": "merge"  // or "replace"
}

Response:

{
  "restored": 5000,
  "skipped": 50,
  "mode": "merge",
  "backup": {
    "id": "uuid-backup-1",
    "created_at": "2025-12-30T00:00:00Z",
    "record_count": 5050
  }
}

WF-CS-011: Conflict Resolution​

Purpose: Handle concurrent writes from multiple devices

Resolution Strategy​

ScenarioResolution
Same content from multiple devicesDeduplicate by content_hash
Concurrent edits to same recordLast-write-wins by updated_at
Delete vs Update conflictUpdate wins (soft delete)
New record collisionUUID-based IDs prevent collision

Deduplication Flow​

WF-CS-012: Cursor Reconciliation​

Purpose: Handle sync drift when cursor gets out of sync

Triggers​

  1. Client cursor ahead of server (server data loss)
  2. Client cursor behind server (missed syncs)
  3. Cursor corruption

Reconciliation Process​

Retention Policy​

Backup TypeUser ScopeTeam ScopeProject ScopeOrg Scope
Incremental7 days7 days7 days7 days
Full90 days90 days90 days365 days
On-DemandUnlimitedUnlimitedUnlimitedUnlimited

Automatic Cleanup Job​

-- Run daily via Cloud Scheduler
DELETE FROM context_backups
WHERE expires_at < NOW()
AND status = 'completed';

Error Handling​

Error Codes​

CodeDescriptionResolution
SYNC_001Invalid cursor positionReconcile cursor
SYNC_002Content hash mismatchRetry with correct hash
SYNC_003Backup not foundCheck backup_id
SYNC_004Checksum verification failedRe-download backup
SYNC_005Permission deniedCheck role/membership
SYNC_006Rate limit exceededRetry with backoff
SYNC_007Storage quota exceededContact admin

Retry Strategy​

RETRY_CONFIG = {
    "max_retries": 3,
    "base_delay": 1.0,  # seconds
    "max_delay": 60.0,  # seconds
    "exponential_base": 2,
    "jitter": True
}

Monitoring & Alerts​

Key Metrics​

MetricDescriptionAlert Threshold
context_sync_push_latencyPush operation latency> 5s
context_sync_pull_latencyPull operation latency> 3s
context_backup_success_rateBackup success percentage< 99%
context_dedup_rateDeduplication percentage> 50% (investigate)
context_cursor_driftCursor position drift> 1000 records

Alert Definitions​

# Cloud Monitoring alert policies
- name: context-sync-high-latency
  conditions:
    - metric: context_sync_push_latency
      threshold: 5s
      duration: 5m
  notification_channels:
    - pagerduty-oncall

- name: context-backup-failure
  conditions:
    - metric: context_backup_success_rate
      threshold: 99%
      comparison: LESS_THAN
  notification_channels:
    - email-alerts
    - pagerduty-oncall

Compliance: CODITECT Workflow Standard v1.0.0