Last Updated: 2025-10-19 Status: ✅ Active - Governance Compliant Governance Version: 1.0.0
Looking for something specific? Start here:
- Current Sprint → /docs/sprints/ (check latest sprint-XX folder)
- Security & Auth → /docs/security/
- System Architecture → /docs/architecture/
- Feature Specs → /docs/features/
- Audit Reports → /docs/audits/
- Development Guides → /docs/guides/
- Quality Standards → /docs/quality/
docs/
├── README.md # This file - master navigation
├── sprints/ # Sprint planning and tracking (NESTED ONLY)
│ ├── sprint-XX/ # Each sprint is a directory
│ │ ├── README.md # Sprint navigation (MANDATORY)
│ │ └── *.md # Sprint documents
├── security/ # Security, auth, compliance (IMMUTABLE)
│ ├── oauth/ # OAuth implementation
│ ├── authentication/ # Auth flows and specs
│ └── audit-trail/ # Security audits (version tracked)
├── architecture/ # System design and architecture
├── features/ # Feature specifications
│ ├── planned/ # Planned features
│ ├── in-progress/ # Active development
│ └── completed/ # Completed features
├── audits/ # Technical audits and analysis
├── processes/ # Development processes and workflows
├── guides/ # How-to guides and tutorials
├── quality/ # Quality standards and governance
└── archived/ # Legacy documentation (read-only)
-
- Prerequisites and installation
- Quick start guide (30 minutes)
- Environment configuration
- Development workflow
- Testing and debugging
- Deployment procedures
- Start here if you're new to the project
-
- Setting up local development environment
- Extension build for localhost:3000
- Testing with local API server
- Architecture Documentation
- System overview and components
- Presentation save flow (current implementation)
- Authentication and security model
- Database schema and RPCs
- Essential reading for understanding the system
-
- Quick diagnostics for common issues
- Error code reference table
- Known issues and workarounds
- Debugging workflows
- Emergency procedures (rollback, recovery)
- Critical for debugging production issues
-
- Test structure and organization
- Running tests (unit, integration, E2E)
- Writing new tests
- Test data management
- Continuous Integration
All documentation MUST follow:
- ✅ Naming Convention: kebab-case-lowercase.md (no CamelCase, no snake_case)
- ✅ Sprint Structure: ALL sprints are nested directories with README.md
- ✅ README Required: Every nested folder (2+ files) needs README.md
- ✅ AI Navigation: Must be findable in ≤3 file reads
- ✅ Security Docs: Immutable with version tracking
- ✅ Link Validation: All internal links must be valid
See: /docs/quality/DOCUMENTATION-GOVERNANCE.md for full rules.
-
- Core tables: users, presentations, device_tokens
- Key RPCs:
rpc_upsert_presentation_from_device,validate_and_touch_token - Performance indexes (Sprint 35 optimizations)
-
Troubleshooting: Database Issues
- SQL query logging
- Migration deployment procedures
- Emergency database recovery
-
Architecture: Authentication & Security
- Device token authentication flow
- Row-Level Security (RLS) policies
- SECURITY DEFINER pattern
- Input validation and defense-in-depth
-
- 401 Unauthorized: Token expired/invalid
- 404 P0001: User not found
- Token validation procedures
-
Architecture: Presentation Save Flow
- Current state (Post Sprint 38)
- Data flow sequence diagram
- Request/Response contract
- Database RPC implementation
-
- Step-by-step diagnostics
- Common error codes (400, 401, 500)
- Network debugging
- API endpoint testing
-
Developer Setup: Development Workflow
- Typical development cycle
- File structure overview
- Hot Module Replacement (HMR)
- Database changes workflow
-
Local Development: Build Environments
- Local vs Production builds
- Environment-specific configs
- Tree-shaking and bundle optimization
-
Database Performance Analysis (13KB)
- Query optimization strategies
- Index recommendations
- Connection pooling
-
Performance Optimization Action Plan (41KB)
- Comprehensive optimization roadmap
- Database, frontend, and DevOps improvements
-
React Optimization Guide (10KB)
- Component optimization techniques
- State management best practices
- Code splitting strategies
-
React/Next.js Optimization Analysis (11KB)
- Next.js specific optimizations
- Bundle size analysis
- Performance monitoring
-
Cache Invalidation System (8KB)
- Cache invalidation strategies
- Implementation patterns
-
Cache Performance Monitoring (9KB)
- Monitoring setup
- Performance metrics
- Alerting thresholds
-
- Extension deployment to Chrome Web Store
- Web app deployment to Netlify
- Database migration deployment
-
Architecture: Deployment Architecture
- Infrastructure overview
- Build system (environment-specific)
- Deployment process
- Sprint 35 CI/CD Strategy (9KB)
- Continuous Integration setup
- Automated testing pipeline
- Deployment automation
- Architecture: Security Audit Trail
- Vulnerability mitigations
- Compliance (GDPR, data minimization)
- Encryption standards
- Troubleshooting: Emergency Procedures
- Production rollback steps
- Database emergency recovery
- Extension store incident response
- Escalation contacts
Sprint 38: Presentation Save Stabilization
- Stabilize save flow after Oct 3-4 emergency fixes
- Enable local development environment
- Comprehensive testing and documentation
- Status: P2 Documentation Complete ✅
- Sprint 26 (Sept 2025): Initial RPC implementation
- Sprint 35 (Sept 2025): Performance optimizations, rollback from Sprint 36
- Sprint 37 (Oct 3-4, 2025): Emergency fixes, RPC simplification
- Sprint 38 (Oct 5, 2025): Stabilization and documentation
See Architecture: Architecture Evolution for detailed timeline.
| Task | Documentation |
|---|---|
| Set up local development | Developer Setup |
| Build extension for local testing | Developer Setup: Build Commands |
| Debug save errors | Troubleshooting: Save Issues |
| Create database migration | Developer Setup: Database Changes |
| Run tests | Testing Guide |
| Deploy to production | Developer Setup: Deployment |
| Rollback production | Troubleshooting: Emergency Rollback |
| Code | Quick Fix | Full Documentation |
|---|---|---|
| 400 VALIDATION_ERROR | Check gamma_url format | Troubleshooting |
| 401 Unauthorized | Re-pair device | Troubleshooting |
| 404 P0001 | Verify user in Supabase Auth | Troubleshooting |
| 500 22004 | Check device token validity | Troubleshooting |
# Development
npm run dev # Start dev server
npm run build:local # Build local extension
npm run test # Run tests
# Database
supabase start # Start local database
supabase db reset # Reset with migrations
supabase db push --linked # Deploy migrations
# Deployment
npm run build # Build production
netlify deploy --prod # Deploy to NetlifyFull command reference: Developer Setup: Quick Reference
- Missing Documentation: Create issue in GitHub with label
documentation - Outdated Information: Submit PR with corrections
- Unclear Instructions: Add comment on specific doc line in GitHub
Level 1: Self-Service
- Check Troubleshooting Guide
- Search GitHub Issues
- Review Architecture Documentation
Level 2: Developer Team
- GitHub Issues: Report bugs
- Slack: #gamma-plugin-dev
- Email: dev@yourcompany.com
Level 3: Infrastructure Team
- Database/migration issues
- Netlify/Supabase outages
- DNS/networking problems
Level 4: Emergency
- Security incidents: security@yourcompany.com
- Production outages: Slack #incidents
- Data corruption: DBA on-call
See Troubleshooting: Support Escalation for full details.
- After Each Sprint: Update architecture and troubleshooting docs
- After Major Incidents: Document root cause and fixes
- Quarterly: Review and update all documentation for accuracy
-
Before Writing:
- Check if documentation already exists
- Review existing structure and style
- Identify target audience (devs, ops, support)
-
Writing Guidelines:
- Use clear, concise language
- Include code examples and commands
- Add diagrams for complex flows
- Link to related documentation
-
After Writing:
- Update this index (README.md)
- Test all commands and procedures
- Request peer review
- Update "Last Updated" date
- Markdown: Use GitHub-flavored markdown
- Code Blocks: Always specify language (
bash,typescript, etc.) - File Paths: Use absolute paths or clearly indicate relative context
- Commands: Include expected output or result
- Links: Use relative links within docs/ folder
- ✅ Created ARCHITECTURE.md - Comprehensive system architecture
- ✅ Created TROUBLESHOOTING.md - Debugging guide with error codes
- ✅ Created DEVELOPER_SETUP.md - Developer onboarding guide
- ✅ Updated LOCAL_DEVELOPMENT.md - Local environment setup
- ✅ Created TESTING.md - Testing guide and best practices
- ✅ Created README.md (this file) - Documentation index
- Database performance optimization documentation
- React/Next.js optimization guides
- CI/CD strategy documentation
Document Maintained By: Development Team Last Major Review: October 2025 (Sprint 38) Next Review: After Sprint 39 or major architectural changes