Infrastructure build to support third-party app integrations

README.md

@@ -63,7 +63,27 @@ Teams can drag-and-rank related task clusters by implementation priority - turni
 
 ## Dev implementation notes
 
-Developers may swap in other LLM SDKs/APIs and alter prompt syntax in `backend/services/clustering.service.js` to experiment with LLMs and platforms of their choice.
+Developers may swap in other LLM SDKs/APIs and alter prompt syntax in `backend/services/clustering.service.ts` to experiment with LLMs and platforms of their choice.
+
+## Integration API
+
+The shared infrastructure that third-party integrations are built on. See [ARCHITECTURE.md](ARCHITECTURE.md) for the design, [ROADMAP.md](ROADMAP.md) for milestones, and [LOW_LEVEL_DESIGN.md](LOW_LEVEL_DESIGN.md) for module contracts.
+
+| Endpoint | Auth | Purpose |
+| --- | --- | --- |
+| `POST /v1/notes` | `Authorization: Bearer <api key>` | Bulk push notes. Body `{ notes: [{ id, text, author, x?, y?, color? }] }`, max 5000 per request. |
+| `POST /v1/webhooks/:provider` | Per-provider request signature | Inbound provider deliveries. Acks immediately, inserts in the background. |
+
+Registered providers live in `backend/config/providers.ts`. `rest` and `linear` carry payload mappings today; `slack`, `github`, and `jira` declare transport and OAuth endpoints only, so adding one of those integrations means writing a single normalizer rather than new plumbing.
+
+Deliveries are deduplicated on `(provider, external_id)` in the `ingest_events` table, which matters beyond tidiness: duplicate notes compress intra-cluster distance and depress the cohesion score.
+
+### Adding a provider
+
+1. Add a slug to `ProviderSlug` in `backend/types/integration.ts`.
+2. Add an entry to `providers` in `backend/config/providers.ts` with its signature scheme, header names, and OAuth endpoints.
+3. Write one normalizer in `backend/config/normalizers.ts` mapping that provider's payload to notes.
+4. Set the provider's signing secret and OAuth credentials in `backend/.env`.
 
 ## Development Roadmap
 
@@ -118,6 +138,23 @@ EOF
 
 Replace placeholder values with your actual keys and database credentials.
 
+#### Integration variables
+
+Only needed once you start using the ingestion endpoints. `TOKEN_ENCRYPTION_KEY` is required by anything that stores third-party credentials; generate one with `openssl rand -base64 32`.
+
+```bash
+cat >> backend/.env << 'EOF'
+TOKEN_ENCRYPTION_KEY=<32 bytes, base64 encoded>
+LINEAR_SIGNING_SECRET=<webhook signing secret from Linear>
+SLACK_SIGNING_SECRET=<webhook signing secret from Slack>
+GITHUB_WEBHOOK_SECRET=<webhook secret from your GitHub App>
+LINEAR_CLIENT_ID=<OAuth client id>
+LINEAR_CLIENT_SECRET=<OAuth client secret>
+EOF
+```
+
+The key must decode to exactly 32 bytes; the backend refuses to encrypt otherwise rather than falling back to something weaker.
+
 ### 3. Set up/run the database
 
 Start DB  for local development (assumes local dev env MacOS and Homebrew installed)
@@ -161,9 +198,10 @@ npm install
 
 ### Start the backend — Production mode
 
-From the `backend/` directory:
+From the `backend/` directory, compile the TypeScript sources and run the output:
 
 ```bash
+npm run build
 npm run start
 ```
 
@@ -171,12 +209,18 @@ The API server starts on **http://localhost:3001** (configurable via the `PORT`
 
 ### Start the backend — Development mode
 
-To start using Nodemon for hot reloads while developing:
+To run the TypeScript sources directly with hot reloads while developing:
 
 ```bash
 npm run dev
 ```
 
+To type-check without emitting:
+
+```bash
+npm run type-check
+```
+
 ### Build the frontend — Production mode
 
 From the `frontend/` directory: