docs(integrations): add integration architecture guide and CLAUDE.md section

[aaight]

Summary

• Created src/integrations/README.md — comprehensive "Adding a New Integration" guide covering all extension points: interface implementation, credential roles, bootstrap registration, webhook routes, router adapters, trigger handlers, and gadgets
• Updated CLAUDE.md — added src/integrations/ to Key Directories and a new "Integration Architecture" section describing the IntegrationModule → IntegrationRegistry pattern, categories (PM/SCM/Alerting), credential roles, and a reference to the README guide

Details

src/integrations/README.md

New guide structured as:

1. Architecture overview — class hierarchy, key files table, data-flow diagram
2. Category descriptions — PM (PMIntegration), SCM (SCMIntegration), Alerting (AlertingIntegration) with method-level detail
3. Step-by-step "Adding a New Integration" — 7 steps with concrete code examples using a hypothetical Linear PM integration:
   • Step 1: Implement the interface (PMIntegration / SCMIntegration / AlertingIntegration)
   • Step 2: Register credential roles via registerCredentialRoles()
   • Step 3: Register in src/integrations/bootstrap.ts
   • Step 4: Add webhook route in src/router/index.ts
   • Step 5: Create RouterPlatformAdapter in src/router/adapters/<provider>.ts
   • Step 6: Create trigger handlers in src/triggers/<provider>/ and wire into builtins.ts
   • Step 7: Add gadgets/capabilities
4. Testing checklist — all extension points verified
5. Reference table — all 4 built-in integrations with file paths

CLAUDE.md

• Added src/integrations/ bullet to Key Directories
• Added "Integration Architecture" section under Key Directories covering: category table, IntegrationModule base contract, IntegrationRegistry API, credential roles, bootstrap, and a link to the README guide

Test plan

• npm run lint — passes (documentation only, no code changes)
• npm run typecheck — passes (no TypeScript changes)
• Guide verified accurate against actual source files (src/integrations/, src/pm/trello/, src/github/scm-integration.ts, src/sentry/alerting-integration.ts, src/router/adapters/trello.ts, src/triggers/builtins.ts)

Trello card: https://trello.com/c/69c1b0699e15862ec755e502

🤖 Generated with Claude Code

🕵️ claude-code · claude-sonnet-4-6 · run details

[nhopeatall]

Summary

Documentation-only PR that adds a comprehensive integration architecture guide. The content is well-structured and mostly accurate against the source code. However, the Step 4 webhook route example shows a pattern that does not match the actual router implementation, which would mislead developers following the guide.

Should Fix

1. Inaccurate webhook route example (src/integrations/README.md, Step 4, lines ~229-242)

The Step 4 webhook route example shows:

app.post('/webhook/trello', verifyWebhookSignature('trello'), async (c) => {
  const payload = await c.req.json();
  return processRouterWebhook(c, 'trello', payload, trelloAdapter, triggerRegistry);
});

But the actual implementation in src/router/index.ts uses a completely different pattern:

app.post('/trello/webhook', createWebhookHandler({
  source: 'trello',
  parsePayload: parseTrelloPayload,
  verifySignature: verifyTrelloWebhookSignature,
  processWebhook: async (payload) => {
    const adapter = new TrelloRouterAdapter();
    const result = await processRouterWebhook(adapter, payload, triggerRegistry);
    return { processed: result.shouldProcess, projectId: result.projectId, decisionReason: result.decisionReason };
  },
}));

Three specific inaccuracies:

1. URL paths are /<provider>/webhook (e.g. /trello/webhook), not /webhook/<provider>
2. Handler pattern uses createWebhookHandler() with a config object (from src/webhook/webhookHandlers.ts), not inline verifyWebhookSignature() middleware
3. processRouterWebhook() signature is (adapter, payload, triggerRegistry) — there is no Hono context c or type string parameter

A developer following this guide would produce code that does not compile.

2. Stale "Adding New Triggers" section (CLAUDE.md, lines 655-659)

The pre-existing "Adding New Triggers" section says "Register in src/triggers/index.ts" but the new guide (correctly) says to register in src/triggers/builtins.ts. Now that this PR adds a detailed integration guide with the correct information, the old section is inconsistent. Consider updating it to match, or replacing it with a reference to the new guide.

🕵️ claude-code · claude-opus-4-6 · run details

[nhopeatall]

Summary

LGTM — thorough and accurate integration architecture documentation. All file paths, interface signatures, registry APIs, bootstrap patterns, and trigger registration patterns verified against the actual source code.

Minor Notes

One small inaccuracy in src/integrations/README.md Step 4: the guide states webhook URL paths follow /<provider>/webhook, but Sentry actually uses /sentry/webhook/:projectId (project-scoped URLs). This is a trivial documentation gap and doesn't affect usability — a developer adding a new integration would discover this from the router code and the Sentry adapter reference. Not worth blocking the PR.

The update to the "Adding New Triggers" section in CLAUDE.md (changing src/triggers/index.ts → src/triggers/builtins.ts and src/triggers/ → src/triggers/<provider>/) correctly reflects the actual codebase structure.

🕵️ claude-code · claude-opus-4-6 · run details