From 65825928ccc140741a6cdfd66b8c48be7be3df70 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Wed, 17 Dec 2025 09:54:33 -0600 Subject: [PATCH] feat(01-03): codebase map templates for integrations and concerns - integrations.md: external APIs, databases, auth, monitoring services - concerns.md: actionable warnings for tech debt, security, performance Phase 1 complete: all 7 codebase map templates created --- get-shit-done/templates/codebase/concerns.md | 299 ++++++++++++++++++ .../templates/codebase/integrations.md | 280 ++++++++++++++++ 2 files changed, 579 insertions(+) create mode 100644 get-shit-done/templates/codebase/concerns.md create mode 100644 get-shit-done/templates/codebase/integrations.md diff --git a/get-shit-done/templates/codebase/concerns.md b/get-shit-done/templates/codebase/concerns.md new file mode 100644 index 000000000..cfbe28629 --- /dev/null +++ b/get-shit-done/templates/codebase/concerns.md @@ -0,0 +1,299 @@ +# Codebase Concerns Template + +Template for `.planning/codebase/CONCERNS.md` - captures known issues and areas requiring care. + +**Purpose:** Surface actionable warnings about the codebase. Focused on "what to watch out for when making changes." + +--- + +## File Template + +```markdown +# Codebase Concerns + +**Analysis Date:** [YYYY-MM-DD] + +## Tech Debt + +**[Area/Component]:** +- Issue: [What's the shortcut/workaround] +- Why: [Why it was done this way] +- Impact: [What breaks or degrades because of it] +- Fix approach: [How to properly address it] + +**[Area/Component]:** +- Issue: [What's the shortcut/workaround] +- Why: [Why it was done this way] +- Impact: [What breaks or degrades because of it] +- Fix approach: [How to properly address it] + +## Known Bugs + +**[Bug description]:** +- Symptoms: [What happens] +- Trigger: [How to reproduce] +- Workaround: [Temporary mitigation if any] +- Root cause: [If known] +- Blocked by: [If waiting on something] + +**[Bug description]:** +- Symptoms: [What happens] +- Trigger: [How to reproduce] +- Workaround: [Temporary mitigation if any] +- Root cause: [If known] + +## Security Considerations + +**[Area requiring security care]:** +- Risk: [What could go wrong] +- Current mitigation: [What's in place now] +- Recommendations: [What should be added] + +**[Area requiring security care]:** +- Risk: [What could go wrong] +- Current mitigation: [What's in place now] +- Recommendations: [What should be added] + +## Performance Bottlenecks + +**[Slow operation/endpoint]:** +- Problem: [What's slow] +- Measurement: [Actual numbers: "500ms p95", "2s load time"] +- Cause: [Why it's slow] +- Improvement path: [How to speed it up] + +**[Slow operation/endpoint]:** +- Problem: [What's slow] +- Measurement: [Actual numbers] +- Cause: [Why it's slow] +- Improvement path: [How to speed it up] + +## Fragile Areas + +**[Component/Module]:** +- Why fragile: [What makes it break easily] +- Common failures: [What typically goes wrong] +- Safe modification: [How to change it without breaking] +- Test coverage: [Is it tested? Gaps?] + +**[Component/Module]:** +- Why fragile: [What makes it break easily] +- Common failures: [What typically goes wrong] +- Safe modification: [How to change it without breaking] +- Test coverage: [Is it tested? Gaps?] + +## Scaling Limits + +**[Resource/System]:** +- Current capacity: [Numbers: "100 req/sec", "10k users"] +- Limit: [Where it breaks] +- Symptoms at limit: [What happens] +- Scaling path: [How to increase capacity] + +## Dependencies at Risk + +**[Package/Service]:** +- Risk: [e.g., "deprecated", "unmaintained", "breaking changes coming"] +- Impact: [What breaks if it fails] +- Migration plan: [Alternative or upgrade path] + +## Missing Critical Features + +**[Feature gap]:** +- Problem: [What's missing] +- Current workaround: [How users cope] +- Blocks: [What can't be done without it] +- Implementation complexity: [Rough effort estimate] + +## Test Coverage Gaps + +**[Untested area]:** +- What's not tested: [Specific functionality] +- Risk: [What could break unnoticed] +- Priority: [High/Medium/Low] +- Difficulty to test: [Why it's not tested yet] + +--- + +*Concerns audit: [date]* +*Update as issues are fixed or new ones discovered* +``` + + +```markdown +# Codebase Concerns + +**Analysis Date:** 2025-01-20 + +## Tech Debt + +**Database queries in React components:** +- Issue: Direct Supabase queries in 15+ page components instead of server actions +- Why: Rapid prototyping during MVP phase +- Impact: Can't implement RLS properly, exposes DB structure to client +- Fix approach: Move all queries to server actions in app/actions/, add proper RLS policies + +**Manual webhook signature validation:** +- Issue: Copy-pasted Stripe webhook verification code in 3 different endpoints +- Why: Each webhook added ad-hoc without abstraction +- Impact: Easy to miss verification in new webhooks (security risk) +- Fix approach: Create shared validateStripeWebhook middleware + +## Known Bugs + +**Race condition in subscription updates:** +- Symptoms: User shows as "free" tier for 5-10 seconds after successful payment +- Trigger: Fast navigation after Stripe checkout redirect, before webhook processes +- Workaround: Stripe webhook eventually updates status (self-heals) +- Root cause: Webhook processing slower than user navigation, no optimistic UI update +- Fix: Poll subscription status after checkout redirect, don't rely solely on webhook + +**Inconsistent session state after logout:** +- Symptoms: User redirected to /dashboard after logout instead of /login +- Trigger: Logout via button in mobile nav (desktop works fine) +- Workaround: Manual URL navigation to /login works +- Root cause: Mobile nav component not awaiting supabase.auth.signOut() +- Fix: Add await to logout handler in MobileNav.tsx + +## Security Considerations + +**Admin role check client-side only:** +- Risk: Admin dashboard pages check isAdmin from Supabase client, no server verification +- Current mitigation: None (relying on UI hiding) +- Recommendations: Add middleware to admin routes, verify role server-side in Server Components + +**Unvalidated file uploads:** +- Risk: Users can upload any file type to avatar bucket (no size/type validation) +- Current mitigation: Supabase bucket limits to 2MB (configured in dashboard) +- Recommendations: Add file type validation (image/* only), virus scanning for larger scale + +## Performance Bottlenecks + +**/api/courses endpoint:** +- Problem: Fetching all courses with nested lessons and authors +- Measurement: 1.2s p95 response time with 50+ courses +- Cause: N+1 query pattern (separate query per course for lessons) +- Improvement path: Use Prisma include to eager-load lessons, add Redis caching + +**Dashboard initial load:** +- Problem: Waterfall of 5 serial API calls on mount +- Measurement: 3.5s until interactive on slow 3G +- Cause: Each component fetches own data independently +- Improvement path: Server Component with single parallel fetch, or React Server Components + +## Fragile Areas + +**Authentication middleware chain:** +- Why fragile: 4 different middleware functions run in specific order (auth -> role -> subscription -> logging) +- Common failures: Middleware order change breaks everything, hard to debug +- Safe modification: Add tests before changing order, document dependencies in comments +- Test coverage: No integration tests for middleware chain (only unit tests) + +**Stripe webhook event handling:** +- Why fragile: Giant switch statement with 12 event types, shared transaction logic +- Common failures: New event type added without handling, partial DB updates on error +- Safe modification: Extract each event handler to separate function, add comprehensive error handling +- Test coverage: Only 3 of 12 event types have tests + +## Scaling Limits + +**Supabase Free Tier:** +- Current capacity: 500MB database, 1GB file storage, 2GB bandwidth/month +- Limit: ~5000 users estimated before hitting limits +- Symptoms at limit: 429 rate limit errors, DB writes fail +- Scaling path: Upgrade to Pro ($25/mo) extends to 8GB DB, 100GB storage + +**Server-side render blocking:** +- Current capacity: ~50 concurrent users before slowdown +- Limit: Vercel Hobby plan (10s function timeout, 100GB-hrs/mo) +- Symptoms at limit: 504 gateway timeouts on course pages +- Scaling path: Upgrade to Vercel Pro ($20/mo), add edge caching + +## Dependencies at Risk + +**react-hot-toast:** +- Risk: Unmaintained (last update 18 months ago), React 19 compatibility unknown +- Impact: Toast notifications break, no graceful degradation +- Migration plan: Switch to sonner (actively maintained, similar API) + +## Missing Critical Features + +**Payment failure handling:** +- Problem: No retry mechanism or user notification when subscription payment fails +- Current workaround: Users manually re-enter payment info (if they notice) +- Blocks: Can't retain users with expired cards, no dunning process +- Implementation complexity: Medium (Stripe webhooks + email flow + UI) + +**Course progress tracking:** +- Problem: No persistent state for which lessons completed +- Current workaround: Users manually track progress +- Blocks: Can't show completion percentage, can't recommend next lesson +- Implementation complexity: Low (add completed_lessons junction table) + +## Test Coverage Gaps + +**Payment flow end-to-end:** +- What's not tested: Full Stripe checkout -> webhook -> subscription activation flow +- Risk: Payment processing could break silently (has happened twice) +- Priority: High +- Difficulty to test: Need Stripe test fixtures and webhook simulation setup + +**Error boundary behavior:** +- What's not tested: How app behaves when components throw errors +- Risk: White screen of death for users, no error reporting +- Priority: Medium +- Difficulty to test: Need to intentionally trigger errors in test environment + +--- + +*Concerns audit: 2025-01-20* +*Update as issues are fixed or new ones discovered* +``` + + + +**What belongs in CONCERNS.md:** +- Tech debt with clear impact and fix approach +- Known bugs with reproduction steps +- Security gaps and mitigation recommendations +- Performance bottlenecks with measurements +- Fragile code that breaks easily +- Scaling limits with numbers +- Dependencies that need attention +- Missing features that block workflows +- Test coverage gaps + +**What does NOT belong here:** +- Opinions without evidence ("code is messy") +- Complaints without solutions ("auth sucks") +- Future feature ideas (that's for product planning) +- Normal TODOs (those live in code comments) +- Architectural decisions that are working fine +- Minor code style issues + +**When filling this template:** +- Be specific with measurements ("500ms p95" not "slow") +- Include reproduction steps for bugs +- Suggest fix approaches, not just problems +- Focus on actionable items +- Prioritize by risk/impact +- Update as issues get resolved +- Add new concerns as discovered + +**Tone guidelines:** +- Professional, not emotional ("N+1 query pattern" not "terrible queries") +- Solution-oriented ("Fix: add index" not "needs fixing") +- Risk-focused ("Could expose user data" not "security is bad") +- Factual ("3.5s load time" not "really slow") + +**Useful for phase planning when:** +- Deciding what to work on next +- Estimating risk of changes +- Understanding where to be careful +- Prioritizing improvements +- Onboarding new Claude contexts +- Planning refactoring work + +**How this gets populated:** +Explore agents detect these during codebase mapping. Manual additions welcome for human-discovered issues. This is living documentation, not a complaint list. + diff --git a/get-shit-done/templates/codebase/integrations.md b/get-shit-done/templates/codebase/integrations.md new file mode 100644 index 000000000..9f8a10034 --- /dev/null +++ b/get-shit-done/templates/codebase/integrations.md @@ -0,0 +1,280 @@ +# 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 + +```markdown +# 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* +``` + + + +**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. +