Gap: Developer Onboarding Guide
Status: 🔴 Not Started Priority: Critical (Pre-Launch) Estimated Effort: 2-3 days
What's Missing
Comprehensive developer onboarding documentation including:
Getting Started
- System requirements (Go version, PostgreSQL, Redis, Docker)
- Repository clone and setup
- Environment variable configuration
- Database setup and seeding
- Running migrations
- Starting local development servers
Architecture Tour
- Codebase walkthrough (internal/ structure)
- Key architectural patterns (repository, service, handler)
- Understanding RLS and multi-tenancy
- Feature organization
- Package dependencies and their purposes
Development Workflow
- Creating a new feature (step-by-step)
- Adding a new API endpoint
- Adding a database table with RLS
- Writing tests for your changes
- Creating migrations
- Code review process
Common Tasks
- Adding a custom field
- Creating a form template
- Adding a segment rule
- Implementing a webhook event
- Adding an automation trigger
Debugging Guide
- RLS troubleshooting (common "not found" issues)
- Connection pool issues
- Migration errors
- Clerk authentication issues
- CORS problems
Tools & Commands
- Makefile commands explained
- Database inspection tools
- Log analysis
- Performance profiling
- Running specific tests
Team Conventions
- Git branch naming
- Commit message format
- PR description template
- Code review checklist
- Documentation requirements
Why Critical
- Team Velocity - New developers must be productive quickly
- Knowledge Transfer - Reduces dependency on senior developers
- Code Quality - Consistent patterns from day one
- Reduced Errors - Understanding RLS prevents data leakage bugs
Current State
- Basic README with installation steps
- Architecture documented in 01-architecture.md
- No step-by-step onboarding guide
- No common tasks walkthrough
- No debugging guide
Impact of Gap
- Days/weeks to onboard new developers
- Repeated questions from new team members
- Inconsistent code patterns
- Fear of touching unfamiliar code
- Difficulty debugging RLS issues
Recommended Location
docs/developers/ directory with:
README.md- Developer onboarding overviewgetting-started.md- Setup and installationarchitecture-tour.md- Codebase walkthroughdevelopment-workflow.md- Daily development taskscommon-tasks.md- Step-by-step task guidesdebugging.md- Debugging and troubleshootingtools.md- Development tools and commandsconventions.md- Team conventions and standards
Dependencies
- Code style guide (Gap #14)
- Testing strategy (Gap #1)
- Local development environment finalized
Success Criteria
- [ ] New developer can set up environment in < 1 hour
- [ ] "Add a new endpoint" tutorial completed
- [ ] "Add a table with RLS" tutorial completed
- [ ] Common debugging scenarios documented
- [ ] Team conventions documented
- [ ] Onboarding checklist created
- [ ] First new developer successfully onboarded using guide