{"slug":"business/CONTRIBUTING","title":"Contributing to Continuity Bridge","section":"business","sectionLabel":"Business","status":"unclassified","type":"document","path":"business/CONTRIBUTING.mdx","bytes":7869,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n\n> **Tier C — Historical.** This document is a point-in-time snapshot preserved for reference. For current architecture, see [CANONICAL_PLATFORM_ARCHITECTURE.md](../architecture/CANONICAL_PLATFORM_ARCHITECTURE.md).\n\nThank you for contributing to Continuity Bridge. This guide outlines our practices for code quality, Cloud-first architecture, and tenant isolation.\n\n## Core Principles\n\n### 1. Cloud-First, No Local State\n\n**All data and logs go to Cloudflare.** There is no local file storage, no persistent agent state, and no client-side caching beyond temporary request context.\n\n**Do:**\n- Write audit logs to `audit_logs` table\n- Store tenant data in D1 (edge) or Fortress (SSOT)\n- Use KV for ephemeral caches (queues, sessions, temporary state)\n\n**Don't:**\n- Write to local filesystem (`fs` module)\n- Store state in memory across requests\n- Use SQLite connections for anything other than migrations\n- Keep agent logs longer than request lifetime\n\n### 2. Per-Tenant Isolation\n\n**Every query must filter by `tenant_id`.** Data leaks across tenants are security violations.\n\n**Template:**\n```typescript\n// ✅ CORRECT\nconst data = await spine.db.query(\n  `SELECT * FROM entities WHERE tenant_id = ? AND entity_type = ?`,\n  [tenantId, type]\n);\n\n// ❌ WRONG — cross-tenant leak\nconst data = await spine.db.query(\n  `SELECT * FROM entities WHERE entity_type = ?`,\n  [type]\n);\n```\n\n### 3. Audit Every Action\n\n**Every material action must be logged.** \"Material\" means: reads from external systems, data writes, approvals, errors, policy decisions.\n\n**Pattern:**\n```typescript\ntry {\n  // Do work\n  const result = await connector.sync(tenantId);\n  \n  // Log success\n  await spine.db.execute(\n    `INSERT INTO audit_logs (tenant_id, actor_id, action, metadata, timestamp)\n     VALUES (?, ?, ?, ?, ?)`,\n    [tenantId, actorId, 'connector.sync', JSON.stringify({ result }), new Date().toISOString()]\n  );\n} catch (err) {\n  // Log error (fail loud)\n  await spine.db.execute(\n    `INSERT INTO audit_logs (tenant_id, actor_id, action, metadata, timestamp)\n     VALUES (?, ?, ?, ?, ?)`,\n    [tenantId, actorId, 'connector.sync.error', JSON.stringify({ error: err.message }), new Date().toISOString()]\n  );\n  throw err;\n}\n```\n\n### 4. No Secrets in Code\n\n**All secrets go in Cloudflare bindings or environment variables.**\n\n**Do:**\n```typescript\nconst NANGO_SECRET = env.NANGO_SECRET_KEY; // From wrangler.toml binding\nconst VAULT_KEY = env.VAULT_ENCRYPTION_KEY; // From CF env vars\n```\n\n**Don't:**\n```typescript\nconst API_KEY = \"sk_live_1234567890\"; // ❌ Hardcoded\nconst token = `Bearer ${secrets.token}`; // ❌ Committed to git\n```\n\n### 5. Borrowed Code Must Be Attributed\n\n**If you adapt code from external sources**, always document:\n- The source repository URL\n- The license (MIT, Apache 2.0, etc.)\n- What you changed and why\n\n**Pattern:**\n```typescript\n/**\n * Based on: https://github.com/example/library (MIT License)\n * Adapted for: Tenant isolation, Cloud-first architecture, per-entity error handling\n */\n  // ...\n}\n```\n\n---\n\n## Development Workflow\n\n### 1. Set Up\n\n```bash\ngit clone https://github.com/NirmalPrinceJ/integratewise-live\ncd integratewise-live\npnpm install\n```\n\n### 2. Branch Naming\n\nUse semantic branch names:\n- `feat/description` — new feature\n- `fix/description` — bug fix\n- `docs/description` — documentation\n- `chore/description` — maintenance\n- `refactor/description` — code cleanup\n\n### 3. Commit Message\n\nWrite clear, structured commits:\n\n```\nfeat: add approval gate for risky actions\n\n- Implement governance.checkPolicy() check in act service\n- Add policy evaluation to approval workflow\n- Log all policy decisions to governance_audit_log\n- Fail loud if policy check unavailable (no silent bypass)\n\nCloses #42\n```\n\n### 4. Code Review Checklist\n\nBefore submitting a PR, verify:\n\n- [ ] **Tenant isolation:** Every query has `WHERE tenant_id = ?`\n- [ ] **Audit logging:** All material actions are logged\n- [ ] **No secrets:** No hardcoded API keys or credentials\n- [ ] **Type safety:** `pnpm typecheck` passes (0 errors)\n- [ ] **Attribution:** Any borrowed code is documented with source + license\n- [ ] **Tests pass:** `pnpm test` succeeds\n- [ ] **No console errors in production:** Only audit logs\n\n### 5. Testing\n\nBefore pushing:\n\n```bash\npnpm typecheck       # TypeScript validation\npnpm lint            # Code style\npnpm test            # Run tests\npnpm preflight       # Full check\n```\n\n---\n\n## Common Patterns\n\n### Logging an Action\n\n```typescript\n// Service: act/src/index.ts\nexport async function executeAction(tenantId: string, proposalId: string, actorId: string): Promise<void> {\n  const proposal = await getProposal(tenantId, proposalId);\n  \n  try {\n    // Execute action via connector\n    const result = await connector.invoke(proposal.action);\n    \n    // Log success\n    await logAudit(tenantId, actorId, 'action.execute', {\n      proposalId,\n      action: proposal.action,\n      result,\n      timestamp: new Date().toISOString()\n    });\n  } catch (err) {\n    // Log error\n    await logAudit(tenantId, actorId, 'action.execute.error', {\n      proposalId,\n      error: err.message,\n      timestamp: new Date().toISOString()\n    });\n    throw err;\n  }\n}\n```\n\n### Querying Tenant Data\n\n```typescript\n// Services should use spine client\n\nconst entities = await spine.query(tenantId, {\n  entity_type: 'lead',\n  filters: { status: 'qualified' },\n  limit: 100\n});\n```\n\n### Per-Tenant Encryption\n\n```typescript\n// Free users get vault-encrypted storage\nif (plan === 'free') {\n  const encrypted = await vault.encrypt(entityData, env.VAULT_KEY);\n  await spine.db.execute(\n    `INSERT INTO entities (tenant_id, entity_type, data_encrypted) VALUES (?, ?, ?)`,\n    [tenantId, 'private_entity', encrypted]\n  );\n}\n```\n\n---\n\n## Architecture Decisions\n\n### Should I Write Directly to D1 or Queue to Pipeline?\n\n**Direct write (fast path):** Use for immediate, non-normalizing operations.\n- Auth decisions\n- Approval gates\n- Session reads\n- Tenant queries\n\n**Queue to pipeline (standard path):** Use for external data, transformations, and audit.\n- Connector sync results\n- Webhook ingress from tools\n- Data normalization\n- Memory consolidation\n\n### Where Should Logging Happen?\n\n**Always log at the point of action.** Each service responsible for its own audit trail.\n\n- `act` logs execution\n- `govern` logs approval decisions\n- `intelligence` logs reasoning sessions\n- `connector` logs sync events\n- `gateway` logs API access\n\n### When to Fail Loud vs. Graceful Degradation?\n\n**Fail loud (throw):** Security, governance, audit writes.\n- If audit log write fails → throw (don't proceed)\n- If approval gate unavailable → throw (don't auto-approve)\n- If tenant isolation check fails → throw (data leak prevention)\n\n**Graceful degradation:** Performance, optional features.\n- If Twin reasoning unavailable → return entities without AI insights\n- If optional KV cache misses → recompute (don't throw)\n- If secondary data source offline → use primary\n\n---\n\n## Reporting Issues\n\n### Security Vulnerabilities\n\n**Do NOT file a public issue.** Email security@integratewise.ai with:\n- Description of the vulnerability\n- Steps to reproduce\n- Potential impact\n\n### Bugs & Feature Requests\n\nUse GitHub issues with:\n- Clear title\n- Reproduction steps (or feature description)\n- Expected vs. actual behavior\n- Relevant logs (audit trail if applicable)\n\n---\n\n## Code of Conduct\n\n- Be respectful and inclusive\n- No harassment, discrimination, or hostility\n- Report violations to founders@integratewise.ai\n\n---\n\n## Questions?\n\n- **Architecture:** See `docs/architecture/`\n- **Operations:** See `docs/operations/`\n- **API:** See `REGISTRY.md`\n- **Platform:** See `README.md`\n\nWelcome aboard! 🚀\n"}