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 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

ID	Name	Trigger	Priority
WF-CS-001	User Context Push	Device sync	P0
WF-CS-002	User Context Pull	Device sync	P0
WF-CS-003	Team Context Push	Team member contribution	P1
WF-CS-004	Team Context Pull	Team sync request	P1
WF-CS-005	Project Context Push	Project contribution	P1
WF-CS-006	Project Context Pull	Project sync request	P1
WF-CS-007	Incremental Backup	Scheduled (hourly)	P0
WF-CS-008	Full Backup	Scheduled (daily)	P1
WF-CS-009	On-Demand Backup	User request	P2
WF-CS-010	Backup Restore	User request	P1
WF-CS-011	Conflict Resolution	Concurrent writes	P0
WF-CS-012	Cursor Reconciliation	Sync drift	P2

---

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

Role	Can Push	Can Pull	Can Backup	Can 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

Role	Can Push	Can Pull	Can Backup	Can 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

Scenario	Resolution
Same content from multiple devices	Deduplicate by content_hash
Concurrent edits to same record	Last-write-wins by updated_at
Delete vs Update conflict	Update wins (soft delete)
New record collision	UUID-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 Type	User Scope	Team Scope	Project Scope	Org Scope
Incremental	7 days	7 days	7 days	7 days
Full	90 days	90 days	90 days	365 days
On-Demand	Unlimited	Unlimited	Unlimited	Unlimited

Automatic Cleanup Job

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

---

Error Handling

Error Codes

Code	Description	Resolution
SYNC_001	Invalid cursor position	Reconcile cursor
SYNC_002	Content hash mismatch	Retry with correct hash
SYNC_003	Backup not found	Check backup_id
SYNC_004	Checksum verification failed	Re-download backup
SYNC_005	Permission denied	Check role/membership
SYNC_006	Rate limit exceeded	Retry with backoff
SYNC_007	Storage quota exceeded	Contact 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

Metric	Description	Alert Threshold
context_sync_push_latency	Push operation latency	> 5s
context_sync_pull_latency	Pull operation latency	> 3s
context_backup_success_rate	Backup success percentage	< 99%
context_dedup_rate	Deduplication percentage	> 50% (investigate)
context_cursor_drift	Cursor 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:
    - slack-alerts
    - pagerduty-oncall

---

Related Documentation

• ADR-044: Custom REST Sync Architecture
• ADR-045: Team/Project Context Sync
• TDD Section 6.1.11-6.1.15: Context Sync Data Models
• SDD Section 4.2.2: Context Sync Service Components

---

Compliance: CODITECT Workflow Standard v1.0.0