.opencode/gsd-core/templates/codebase/integrations.md

External Integrations Template

Template for .planning/codebase/INTEGRATIONS.md - captures external service dependencies.

Purpose: Document what external systems this codebase communicates with. Focused on "what lives outside our code that we depend on."

---

File Template

# External Integrations

**Analysis Date:** [YYYY-MM-DD]

## APIs & External Services

**Payment Processing:**
- [Service] - [What it's used for: e.g., "subscription billing, one-time payments"]
  - SDK/Client: [e.g., "stripe npm package v14.x"]
  - Auth: [e.g., "API key in STRIPE_SECRET_KEY env var"]
  - Endpoints used: [e.g., "checkout sessions, webhooks"]

**Email/SMS:**
- [Service] - [What it's used for: e.g., "transactional emails"]
  - SDK/Client: [e.g., "sendgrid/mail v8.x"]
  - Auth: [e.g., "API key in SENDGRID_API_KEY env var"]
  - Templates: [e.g., "managed in SendGrid dashboard"]

**External APIs:**
- [Service] - [What it's used for]
  - Integration method: [e.g., "REST API via fetch", "GraphQL client"]
  - Auth: [e.g., "OAuth2 token in AUTH_TOKEN env var"]
  - Rate limits: [if applicable]

## Data Storage

**Databases:**
- [Type/Provider] - [e.g., "PostgreSQL on Supabase"]
  - Connection: [e.g., "via DATABASE_URL env var"]
  - Client: [e.g., "Prisma ORM v5.x"]
  - Migrations: [e.g., "prisma migrate in migrations/"]

**File Storage:**
- [Service] - [e.g., "AWS S3 for user uploads"]
  - SDK/Client: [e.g., "@aws-sdk/client-s3"]
  - Auth: [e.g., "IAM credentials in AWS_* env vars"]
  - Buckets: [e.g., "prod-uploads, dev-uploads"]

**Caching:**
- [Service] - [e.g., "Redis for session storage"]
  - Connection: [e.g., "REDIS_URL env var"]
  - Client: [e.g., "ioredis v5.x"]

## Authentication & Identity

**Auth Provider:**
- [Service] - [e.g., "Supabase Auth", "Auth0", "custom JWT"]
  - Implementation: [e.g., "Supabase client SDK"]
  - Token storage: [e.g., "httpOnly cookies", "localStorage"]
  - Session management: [e.g., "JWT refresh tokens"]

**OAuth Integrations:**
- [Provider] - [e.g., "Google OAuth for sign-in"]
  - Credentials: [e.g., "GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET"]
  - Scopes: [e.g., "email, profile"]

## Monitoring & Observability

**Error Tracking:**
- [Service] - [e.g., "Sentry"]
  - DSN: [e.g., "SENTRY_DSN env var"]
  - Release tracking: [e.g., "via SENTRY_RELEASE"]

**Analytics:**
- [Service] - [e.g., "Mixpanel for product analytics"]
  - Token: [e.g., "MIXPANEL_TOKEN env var"]
  - Events tracked: [e.g., "user actions, page views"]

**Logs:**
- [Service] - [e.g., "CloudWatch", "Datadog", "none (stdout only)"]
  - Integration: [e.g., "AWS Lambda built-in"]

## CI/CD & Deployment

**Hosting:**
- [Platform] - [e.g., "Vercel", "AWS Lambda", "Docker on ECS"]
  - Deployment: [e.g., "automatic on main branch push"]
  - Environment vars: [e.g., "configured in Vercel dashboard"]

**CI Pipeline:**
- [Service] - [e.g., "GitHub Actions"]
  - Workflows: [e.g., "test.yml, deploy.yml"]
  - Secrets: [e.g., "stored in GitHub repo secrets"]

## Environment Configuration

**Development:**
- Required env vars: [List critical vars]
- Secrets location: [e.g., ".env.local (gitignored)", "1Password vault"]
- Mock/stub services: [e.g., "Stripe test mode", "local PostgreSQL"]

**Staging:**
- Environment-specific differences: [e.g., "uses staging Stripe account"]
- Data: [e.g., "separate staging database"]

**Production:**
- Secrets management: [e.g., "Vercel environment variables"]
- Failover/redundancy: [e.g., "multi-region DB replication"]

## Webhooks & Callbacks

**Incoming:**
- [Service] - [Endpoint: e.g., "/api/webhooks/stripe"]
  - Verification: [e.g., "signature validation via stripe.webhooks.constructEvent"]
  - Events: [e.g., "payment_intent.succeeded, customer.subscription.updated"]

**Outgoing:**
- [Service] - [What triggers it]
  - Endpoint: [e.g., "external CRM webhook on user signup"]
  - Retry logic: [if applicable]

---

*Integration audit: [date]*
*Update when adding/removing external services*

```markdown # External Integrations

Analysis Date: 2025-01-20

APIs & External Services

Payment Processing:

• Stripe - Subscription billing and one-time course payments
  • SDK/Client: stripe npm package v14.8
  • Auth: API key in STRIPE_SECRET_KEY env var
  • Endpoints used: checkout sessions, customer portal, webhooks

Email/SMS:

• SendGrid - Transactional emails (receipts, password resets)
  • SDK/Client: @sendgrid/mail v8.1
  • Auth: API key in SENDGRID_API_KEY env var
  • Templates: Managed in SendGrid dashboard (template IDs in code)

External APIs:

• OpenAI API - Course content generation
  • Integration method: REST API via openai npm package v4.x
  • Auth: Bearer token in OPENAI_API_KEY env var
  • Rate limits: 3500 requests/min (tier 3)

Data Storage

Databases:

• PostgreSQL on Supabase - Primary data store
  • Connection: via DATABASE_URL env var
  • Client: Prisma ORM v5.8
  • Migrations: prisma migrate in prisma/migrations/

File Storage:

• Supabase Storage - User uploads (profile images, course materials)
  • SDK/Client: @supabase/supabase-js v2.x
  • Auth: Service role key in SUPABASE_SERVICE_ROLE_KEY
  • Buckets: avatars (public), course-materials (private)

Caching:

• None currently (all database queries, no Redis)

Authentication & Identity

Auth Provider:

• Supabase Auth - Email/password + OAuth
  • Implementation: Supabase client SDK with server-side session management
  • Token storage: httpOnly cookies via @supabase/ssr
  • Session management: JWT refresh tokens handled by Supabase

OAuth Integrations:

• Google OAuth - Social sign-in
  • Credentials: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET (Supabase dashboard)
  • Scopes: email, profile

Monitoring & Observability

Error Tracking:

• Sentry - Server and client errors
  • DSN: SENTRY_DSN env var
  • Release tracking: Git commit SHA via SENTRY_RELEASE

Analytics:

• None (planned: Mixpanel)

Logs:

• Vercel logs - stdout/stderr only
  • Retention: 7 days on Pro plan

CI/CD & Deployment

Hosting:

• Vercel - Next.js app hosting
  • Deployment: Automatic on main branch push
  • Environment vars: Configured in Vercel dashboard (synced to .env.example)

CI Pipeline:

• GitHub Actions - Tests and type checking
  • Workflows: .github/workflows/ci.yml
  • Secrets: None needed (public repo tests only)

Environment Configuration

Development:

• Required env vars: DATABASE_URL, NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY
• Secrets location: .env.local (gitignored), team shared via 1Password vault
• Mock/stub services: Stripe test mode, Supabase local dev project

Staging:

• Uses separate Supabase staging project
• Stripe test mode
• Same Vercel account, different environment

Production:

• Secrets management: Vercel environment variables
• Database: Supabase production project with daily backups

Webhooks & Callbacks

Incoming:

• Stripe - /api/webhooks/stripe
  • Verification: Signature validation via stripe.webhooks.constructEvent
  • Events: payment_intent.succeeded, customer.subscription.updated, customer.subscription.deleted

Outgoing:

• None

---

Integration audit: 2025-01-20 Update when adding/removing external services

</good_examples>

<guidelines>
**What belongs in INTEGRATIONS.md:**
- External services the code communicates with
- Authentication patterns (where secrets live, not the secrets themselves)
- SDKs and client libraries used
- Environment variable names (not values)
- Webhook endpoints and verification methods
- Database connection patterns
- File storage locations
- Monitoring and logging services

**What does NOT belong here:**
- Actual API keys or secrets (NEVER write these)
- Internal architecture (that's ARCHITECTURE.md)
- Code patterns (that's PATTERNS.md)
- Technology choices (that's STACK.md)
- Performance issues (that's CONCERNS.md)

**When filling this template:**
- Check .env.example or .env.template for required env vars
- Look for SDK imports (stripe, @sendgrid/mail, etc.)
- Check for webhook handlers in routes/endpoints
- Note where secrets are managed (not the secrets)
- Document environment-specific differences (dev/staging/prod)
- Include auth patterns for each service

**Useful for phase planning when:**
- Adding new external service integrations
- Debugging authentication issues
- Understanding data flow outside the application
- Setting up new environments
- Auditing third-party dependencies
- Planning for service outages or migrations

**Security note:**
Document WHERE secrets live (env vars, Vercel dashboard, 1Password), never WHAT the secrets are.
</guidelines>